get identity config

Description

Returns the identity security configuration for PageSeeder.

The identity security configuration is specified in the identity-config.xml file and holds information to use an external Single-Sign-On app to sign in to PageSeeder. It includes the list of external identity providers, the email domains they are associated with and which portal end-users should use to sign in.

This service does not return the contents of the identity-config.xml directly, instead it returns a serialized version of the actual identity security configuration.

Usage

If a domain is exclusively managed by an external identify provider, users cannot change their email address using PageSeeder. Client apps can use this service to determine whether to refer users to their external identity provider.

This service only returns the configuration for the client apps to manage, it does not handle any of the SSO interactions.

Parameters

Permission

This service requires Administrator.

Response

Returns the following XML:

<identity-config
    [default-authentication="[none|internal|external|any]"]
    [default-provider="[provider ID]">
 [<portal title="[title]" href="[url]" />]
  <provider [id="[provider ID]"] [title=""] [description=""]
            client-id="[registered client ID with the external identity provider]"
            authority-url="[authority URL of the external identity provider]"/>
  ...
  <domain name="[domain]"
          [authentication="[none|internal|external|any]"]
          [providers="[provider IDs]"]/>
  ...
<identity-config>

Or its equivalent in JSON:

{
  "defaultAuthentication" : string,
  "defaultProvider": string,
  "portal": { "title":string, "href":string },
  "externalProviders": [
    {
      "id": string,
      "title": string,
      "description": string,
      "clientId": string,
      "authorityUrl": string
    }
  ],
  "externalDomains": [
    {
      "name": string,
      "authentication": string,
      "providers": string
    }
  ]
}

Example: SSO for single domain

In the following example, the domain example.org is exclusively managed by Google, users whose email address end with @example.org must authenticate with Google first. PageSeeder provides a link to the page “SSO Example” to allow them to authenticate to Google and be redirected to PageSeeder afterwards.

<identity-config>
  <!-- Link to SSO page that the user will be shown -->
  <portal title="SSO Example" href="https://sso.example.org/" />
  <!-- List allowed external identity providers here -->
  <provider title="Google" description="Google auth for example.org"
            authority-url="https://accounts.google.com"
            client-id="1234567890-fakeid.apps.googleusercontent.com" />
  <!-- List affected domains -->
  <domain name="example.org" authentication="external" />
</identity-config>

Or

{
  "portal": {
    "title": "SSO Example",
    "href: "https://sso.example.org/"
  },
  "externalProviders": [
    {
      "title": "Google",
      "description": "Google auth for example.org",
      "clientId": "1234567890-fakeid.apps.googleusercontent.com",
      "authorityUrl": "https://accounts.google.com"
    }
  ],
  "externalDomains": [
    {
      "name": "example.org",
      "authentication": external
    }
  ]
}

Example: no configuration

If your PageSeeder instance does not define an identify configuration file or if an error occurs while loading the identity configuration file, this service returns an empty configuration:

<identity-config default-authentication="internal" />

Or 

{
  "defaultAuthentication": "internal",
  "external-providers": [],
  "external-domains": []
}

Error Handling

No specific errors expected for this generator.

If the identity configuration is invalid, an empty configuration is returned.