Skip to content

Single Sign On (SSO)

P6 Auth uses SSO Connections to define provider specific configuration for authentication and user provisioning.

One or more SSO Connections may be created for a single Platform 6 Instance. Each SSO Connection has a name and SSO Connections are always listed in name order.

Authentication

An important attribute of an SSO Connection is the Login Context (URL). This URL allows the Platform 6 Portal Login page to identify which SSO connect using... buttons to display to the user.

For example, if my organisation is allocated a custom login context of: https://mybiz.portal.amalto.com then this URL will be used to find all SSO Connections defined with this as the Login Context. The SSO Connections found will be used to display the SSO connection button(s) on the login page.

By default, the display of SSO connection buttons will disable the display of the standard Amalto username/password login fields.

SSO Login Two

Note

This behaviour can be overridden using the json attribute allowSSOAndBaseLogin: true for the defined client section in the portal_config.json file.

SSO Login One

Each SSO Connection has a Connection Type attribute which may be set to either:

Currently only OIDC and EX_FED are supported.

The SSO Connection details form is available from a tab of the Administration menu in the Platform 6 Portal:

SSO Connections

A user requires the following permissions to use the SSO Connections configuration:

  • sso=read (to list and review the SSO Connections)

  • sso=edit (to add and update SSO Connections)

  • sso=delete (to remove an SSO Connection)

Disabled SSO Connection

If an SSO Connection is not enabled (disabled) it will still be shown on the associated login page but will not be selectable:

SSO Login Three

OIDC Connection Type Properties

OIDC property values will vary depending upon the authentication provider being used. It is essential these values match those defined by your provider.

Note

A good tool to validate low level OIDC configuration is: https://oidcdebugger.com/

Property Name Description
oidc.provider.url Mandatory (unless oidc.discovery=false). The root context used to discover all other OIDC configuration. We wil append /.well-known/openid-configuration to this URL to request provider configuration.
oidc.client.id Mandatory. Provider allocated. It is typically a UUID
oidc.authorize.request.scopes Mandatory. Space separated OIDC defined values, typically openid or openid email
oidc.authorize.use.state Optional. Use and validate the state parameter in authorize requests (https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) (default: false)
oidc.provider.tls.trustany Optional. Set to true to disable TLS/SSL certificate validation on provider endpoints
oidc.client.secret Optional. Provider allocated. Not always required but must match provider configured value
oidc.token.signature Optional. Signature type used to sign OIDC id_token. One of: NONE, RS256, HMAC (default: RS256)
oidc.email.claim Optional. Claim set attribute to inspect for email address to use for auto provisioning, if the email claim set attribute is not found.
oidc.given.name.claim Optional. Claim set attribute to inspect for given name to use for auto provisioning. (default: given_name)
oidc.family.name.claim Optional. Claim set attribute to inspect for family name to use for auto provisioning. (default: family_name)
oidc.disable.claim.mapping Optional. If true, disable any attempt to map family name and given name claims during auto provisioning. (default: false)
oidc.claim.string.match Optional. A string claim set attribute that must be present and who’s value must match the given value otherwise authentication will be denied. (format: key=value)
oidc.claim.stringlist.match Optional. A string list claim set attribute that must be present and contain all the values given. (format key=value,value,…)
oidc.discovery Optional. Does the OIDC Identity Provider support endpoint discovery? (default: true)
oidc.flow.implicit Optional. The authorization server will return an ID token directly back to the client? (default: true)
oidc.authorization.endpoint Optional. Authorization endpoint if oidc.discovery is not supported.
oidc.end.session.endpoint Optional. End session endpoint if oidc.discovery is not supported.
oidc.response.type Optional. The response type to request from the Authorization endpoint. One or more of id_token code token (default: id_token)
oidc.token.endpoint Optional. An endpoint to use to exchange a code for an access_token. Only required if oidc.flow.implicit=false and oidc.response.type=code.
oidc.userinfo.endpoint Optional. When using a code or hybrid flow, a user information endpoint is required to collect email and user names
oidc.end.session.with.hint Optional. Used with Microsoft AD FS to enable the passing of the OIDC id_token as parameter id_token_hint to the end session endpoint. Set as : true
oidc.ui.redirect.uri Optional. An additional redirection made by the ui after processing the id_token or code in the OIDC flow. (default: none)
oidc.response.mode Optional. An override for the response_mode requested of the Authorization endpoint. One of fragment, query or form_post. (default: ‘’)
oidc.pkce Optional. Enables the use of (RFC 7636) - an extension to the Authorization Code flow (default: false)
oidc.pkce.method Optional. The PKCE challenge method to use. Either plain or S256 (default: plain)
oidc.pkce.code.verifier Internal use only
oidc.pkce.code.challenge Internal use only
p6mc.auto.provision.account Internal use only
p6mc.auto.provision.baseContext Internal use only
p6mc.auto.provision.infoPath Internal use only
debug Optional. (default: false) If true the server will log details of all interactions with the OIDC IDP. Must be set to false in production.
auto Optional. (default: false) If true and only one SSO Connection matches the current Login Context (URL) (and the Portal json attribute: allowSSOAndBaseLogin == false) the Portal will not display an SSO image button and auto initiate the SSO Connection

Provider Configuration

In addition to the above, the provider requires the prior registration of the following:

  • Redirect URI: This value should be set to the Login Context (URL) specified on the SSO Connection

Claims Matching

It is possible to use the optional claims match properties to restrict access to only a subset of SSO users. Claims matching is a mechanism whereby P6 Auth will check an SSO users claim set when they attempt a login. If the specified (String or StringList) claim set values do not match the configured and expected values, authenticated access is denied.

Some OIDC providers allow the administrator to add custom claims to a user. This will vary depending upon provider. However, consider the example of adding a users department name to their claim set and only allowing users from that department access to Platform 6. By adding the following property this could be achieved:

  • oidc.claim.string.match: dept=procurement

Another example when using Microsoft Azure as your provider is to enable group membership claims. To activate this you need to add the following to the application manifest of the Platform 6 App definition using the Azure portal:

"groupMembershipClaims": "SecurityGroup",

Next you need to identify the OID of the group you wish to restrict access by. As an example, consider we created an Azure User Group called platform6 and an OID of: ec6d1489-b580-4078-a536-89d1e63126ad

Adding the following claims match property will restrict access to only those users in the platform6 group:

  • oidc.claim.stringlist.match: groups=ec6d1489-b580-4078-a536-89d1e63126ad

EX_FED Connection Type Properties

EX_FED property values will vary depending upon the federated IDP being used.

Property Name Description
oidc.jwks.endpoint Mandatory (unless oidc.jwks.x509). The URL used to discover the OIDC JWKS configuration. Will typically be: https://[federated IDP]/.well-known/openid-configuration/jwks
oidc.jwks.x509 Mandatory (unless oidc.jwks.endpoint). Base64 encoded JWKS public cert in X.509 format
oidc.jwks.kid Optional (unless oidc.jwks.x509). The key id must match the kid in the JOSE header of the JWT
oidc.given.name.claim Optional. Claim set attribute to inspect for given name to use for auto provisioning. (default: given_name)
oidc.family.name.claim Optional. Claim set attribute to inspect for family name to use for auto provisioning. (default: family_name)
exfed.token.email.claim Mandatory. Comma separated list of claim set attribute(s) to inspect for email address to use for auto provisioning, if the email claim set attribute is not found.
exfed.token.header.type Optional. (default: at+jwt) See: https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-algorithms-40
exfed.token.header.algorithm Optional. (default: RS256) See: https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-algorithms-40
exfed.token.claims Optional. (default: `) Comma separated list of claims that MUST be present in the provided JWT: should at least contain the value ofexfed.token.email.claim`
exfed.auto.provision.permissions.claim Optional. Claim in supplied JWT to use as an index to perform an org tree lookup for permissions
exfed.auto.provision.permissions.org.path Optional. (unless exfed.auto.provision.permissions.claim)
exfed.auto.provision.user.property.claims.mappings Optional. Comma separated list of name=key pairs where name is the claim name and key is the user property key the claim is mapped to
exfed.userinfo.url Optional. THE URL of an endpoint returning a userinfo JSON that can be used to recover PII such as email, firstname and lastname if not present in the given subject_token

Note

The use of oidc.jwks.x509/kid is not recommended for production use; it serves as a convenient workaround when provision of a JWKS endpoint is complicated!

Token Exchange Implementation

Parameters to the /token exchange endpoint when grant_type=urn:ietf:params:oauth:grant-type:token-exchange

  • audience: The name of the Platform 6 instance for which an access token is requested
  • subject_token_type: Only urn:ietf:params:oauth:token-type:access_token supported
  • subject_token: Base64 encoded JWT from federated IDP

Note

The Issuer (iss) claim of the subject_token must match the Login Context (URL) defined with this SSO Connection

User Property Mapping Based on JWT Claim Value Lookup (Used only when Auto Provisioning a new user)
  • The lookup claim values are taken from the provided JWT using the exfed.auto.provision.user.property.claims.mappings property.
  • The mappings are expressed as a comma separated list of name=key pairs
  • If a claim is found using the name given then its value (which must be a String) is assigned as a user property value with the given key
Permissions Assignment Based on JWT Claim Value Lookup (Used only when Auto Provisioning a new user)
  • The lookup claim value is taken from the provided JWT using the exfed.auto.provision.permissions.claim property to identify the claim.
  • If a lookup claim value is found, an organisation tree path is created by appending to the given exfed.auto.provision.permissions.org.path property.
  • The path is used to lookup a node in the org tree. If the node exists, the property values are read from the node.
  • Node properties with names: PermissionSet1..nn are read and the corresponding property values used as the names of Permission Set(s) to assign to the auto-provisioned user.

Note

These permission assignments are in addition to any permissions selected in the auto-provision permissions list of the SSO Connection

Auto Provisioning

If selected, Auto-provision will automatically add a P6 User if one does not exist when an SSO user first logs in. It will use an email address identified in the claim set as the P6 User email. If a new user is created, they will be assigned the permissions and initial organizational tree position specified on the SSO Connection.

Note

When possible the firstname and lastname of an SSO user are also collected and used in user profile creation.

P6 User Email Identification Using Claim Set

A users email is determined by examining the claim set provided by the SSO provider. The email is generally available in the claim set if the property oidc.authorize.request.scopes contains email However this is not always the case, and you may need to specify an alternative claim set attribute to use if the email claim is missing or empty. The following property is used to specify the claim set attribute to use in this case:

  • oidc.email.claim

Note

This value should be set to upn when interacting with Azure Active Directory users

SSO Provisioned User Indicators

When listing users using the Administration menu, P6 users that have been created as the result of SSO provisioning will appear visually different to other users as they will be displayed with the SSO ‘badge’.

SSO User

Provider Integrated User Provisioning

Warning

Provider integrated user provisioning is not supported in the current version of Platform 6