Unlike other authentication methods, it's not possible to configure OpenID Connect authentication method completely with SSO Management UI, but SSO Management API is required. All the steps here are done using Management API.

OpenID Connect is a subset of OAuth 2.0. Read more on configuring OAuth 2.0 in SSO from OAuth2 - SSO

Reference of OAuth 2.0 and OpenID Connect 1.0 client implementation in SSO Server authentication method OpenIDConnectMethod.

Registration

Sequence diagram

Integrator is the person configuring the system.

Process

Only the requests to SSO have examples as IDP is considered as an external system in this example.

1. Create OpenIDConnectMethod authentication method in SSO Server

To create an enabled authentication method named oidc.method.1 with specific title and configuration use this API call:

Request example

PUT /sso-api/method/oidc.method.1 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJjdHkiOiJ...7u3wua_Sw
Content-Type: application/x-www-form-urlencoded
Host: sso.example.com

methodType=OpenID%20Connect&className=ubilogin.method.provider.openidconnect.OpenIDConnectMethod&enabled=true&title=OIDC%20method&configuration=OperationMode%20private

Response example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "method",
    "id": "/method/oidc.method.1",
    "attributes": {
        "name": "oidc.method.1",
        "methodType": "OpenID Connect",
        "className": "ubilogin.method.provider.openidconnect.OpenIDConnectMethod",
        "enabled": true,
        "title": "OIDC method",
        "configuration": [
            "OperationMode private"
        ]
    }
}

2. Get provider metadata from your OpenID Connect provider

If provider metadata is not available then you need to manually construct provider metadata with required parameters for next step.

3. Register provider metadata with SSO Server with the metadata from issuer

To register the metadata from previous step to the method named oidc.method.1 use this API call:

Request example

PUT /sso-api/method/oidc.method.1/$attribute/metadata HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJjdHkiOiJ...7u3wua_Sw
Host: sso.example.com

{
   "issuer":"https://oidc.provider.example.com",
   "authorization_endpoint":"https://oidc.provider.example.com/oidc/authorize",
   "token_endpoint":"https://oidc.provider.example.com/oidc/token",
   "jwks_uri":"https://oidc.provider.example.com/oidc/jwks",
   "response_types_supported":[
      "code"
   ],
   "grant_types_supported":[
      "authorization_code"
   ],
   "id_token_encryption_alg_values_supported":[
      "RSA-OAEP"
   ],
   "id_token_encryption_enc_values_supported":[
      "A128GCM"
   ],
   "id_token_signing_alg_values_supported":[
      "RS256"
   ],
   "request_object_signing_alg_values_supported":[
      "RS256"
   ],
   "token_endpoint_auth_methods_supported":[
      "private_key_jwt"
   ],
   "request_parameter_supported":true,
   "request_uri_parameter_supported":false,
   "display_values_supported":[
      "page"
   ],
   "scopes_supported":[
      "openid"
   ],
   "response_modes_supported":[
      "query",
      "fragment"
   ],
   "claims_supported":[
      "urn:oid:2.5.4.4",
      "urn:oid:1.2.246.575.1.14",
      "sub",
      "urn:oid:1.3.6.1.5.5.7.9.1",
      "urn:oid:1.2.246.21"
   ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "issuer":"https://oidc.provider.example.com",
   "authorization_endpoint":"https://oidc.provider.example.com/oidc/authorize",
   "token_endpoint":"https://oidc.provider.example.com/oidc/token",
   "jwks_uri":"https://oidc.provider.example.com/oidc/jwks",
   "response_types_supported":[
      "code"
   ],
   "grant_types_supported":[
      "authorization_code"
   ],
   "id_token_encryption_alg_values_supported":[
      "RSA-OAEP"
   ],
   "id_token_encryption_enc_values_supported":[
      "A128GCM"
   ],
   "id_token_signing_alg_values_supported":[
      "RS256"
   ],
   "request_object_signing_alg_values_supported":[
      "RS256"
   ],
   "token_endpoint_auth_methods_supported":[
      "private_key_jwt"
   ],
   "request_parameter_supported":true,
   "request_uri_parameter_supported":false,
   "display_values_supported":[
      "page"
   ],
   "scopes_supported":[
      "openid"
   ],
   "response_modes_supported":[
      "query",
      "fragment"
   ],
   "claims_supported":[
      "urn:oid:2.5.4.4",
      "urn:oid:1.2.246.575.1.14",
      "sub",
      "urn:oid:1.3.6.1.5.5.7.9.1",
      "urn:oid:1.2.246.21"
   ]
}

4. Read jwks_uri parameter from provider metadata, and get provider JSON Web Keys

Get the provider's keys from URL found in metadata field jwks_uri

5. Register provider keys with SSO Server

To register the provider keys from previous step to the method named oidc.method.1 use this API call:

Example request

PUT /sso-api/method/oidc.method.1/$attribute/jwks HTTP/1.1
Accept: application/jwk-set+json
Content-Type: application/jwk-set+json
Authorization: Bearer eyJjdHkiOiJ...7u3wua_Sw
Host: sso.example.com
{ "keys": [
  {
    "kty": "RSA",
    "e": "AQAB",
    "use": "sig",
    "kid": "keyid9876",
    "alg": "RS256",
    "n": "05Csoq8qI...aYvRL1V_8"
  }
]}

Example response

HTTP/1.1 200 OK
Content-Type: application/jwk-set+json

{ "keys": [
  {
    "kty": "RSA",
    "e": "AQAB",
    "use": "sig",
    "kid": "keyid9876",
    "alg": "RS256",
    "n": "05Csoq8qI...7aYvRL1V_8"
  }
]}

6. Get registration request from SSO Server

If provider does not support registration protocol then this step is optional but you can use the response body as a base for manually building the registration response in step 8.

Example request

GET /sso-api/method/oidc.method.1/$attribute/registration HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJjdHkiOiJ...7u3wua_Sw
Host: sso.example.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "redirect_uris": [
        "https://sso.example.com/uas/return/oidc.method.1/redirect"
    ],
    "grant_types": [
        "authorization_code"
    ],
    "response_types": [
        "code"
    ],
    "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks",
    "scope": "openid",
    "id_token_signed_response_alg": "RS256",
    "id_token_encrypted_response_alg": "RSA-OAEP",
    "id_token_encrypted_response_enc": "A128GCM",
    "request_object_signing_alg": "RS256",
    "token_endpoint_auth_method": "private_key_jwt"
}

7. Send registration request to OpenID Connect provider, and receive registration response

If provider does not support registration protocol then you need another method to register SSO Server as client and receive client_id and possible client_secret. Then you need to add them to the payload for next step manually.

If your OpenID Connect provider is also SSO you need to manually edit the registration request json to replace the jwks_uri with the actual jwks that can be found from the URI. You should not have both jwks_uri and jwks in the same request.

Example of manually edited registration request

{
    "redirect_uris": [
        "https://sso.example.com/uas/return/oidc.method.1/redirect"
    ],
    "grant_types": [
        "authorization_code"
    ],
    "response_types": [
        "code"
    ],
    "scope": "openid",
    "id_token_signed_response_alg": "RS256",
    "id_token_encrypted_response_alg": "RSA-OAEP",
    "id_token_encrypted_response_enc": "A128GCM",
    "request_object_signing_alg": "RS256",
    "token_endpoint_auth_method": "private_key_jwt",
    "jwks": { 
        "keys": [
            {
                "kty": "RSA",
                "e": "AQAB",
                "use": "sig",
                "kid": "keyid9876",
                "alg": "RS256",
                "n": "05Csoq8qI...7aYvRL1V_8"
            }
        ]
    }
}

8. Register registration response with SSO Server

This example has additional configuration for using acr_values in OIDC client and it is using keys for token endpoint authentication instead of a secret. If the provider does not support the registration protocol then you need to manually construct the registration response with the required parameters.

Example request

PUT /sso-api/method/oidc.method.1/$attribute/registration HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJjdHkiOiJ...7u3wua_Sw
Host: sso.example.com


{
    "redirect_uris": [
        "https://sso.example.com/uas/return/oidc.aktia.1/redirect"
    ],
    "grant_types": [
        "authorization_code"
    ],
    "response_types": [
        "code"
    ],
    "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks",
    "scope": "openid scope1",
    "id_token_signed_response_alg": "RS256",
    "id_token_encrypted_response_alg": "RSA-OAEP",
    "id_token_encrypted_response_enc": "A128GCM",
    "request_object_signing_alg": "RS256",
    "token_endpoint_auth_method": "private_key_jwt",
    "client_id": "test-client",
    "ubisecure_request_object_query_parameters": [
    	"client_id",
    	"scope",
    	"response_type",
    	"acr_values"
    ],
    "ubisecure_request_parameters": {
    	"acr_values": "acr1"
    }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json


{
    "redirect_uris": [
        "https://sso.example.com/uas/return/oidc.aktia.1/redirect"
    ],
    "grant_types": [
        "authorization_code"
    ],
    "response_types": [
        "code"
    ],
    "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks",
    "scope": "openid scope1",
    "id_token_signed_response_alg": "RS256",
    "id_token_encrypted_response_alg": "RSA-OAEP",
    "id_token_encrypted_response_enc": "A128GCM",
    "request_object_signing_alg": "RS256",
    "token_endpoint_auth_method": "private_key_jwt",
    "client_id": "test-client",
    "ubisecure_request_object_query_parameters": [
        "client_id",
        "scope",
        "response_type",
        "acr_values"
    ],
    "ubisecure_request_parameters": {
        "acr_values": "acr1"
    }
}

After creating the OIDC method it needs to be linked with the appropriate sites, applications and allowed to needed users.

Management API endpoints

/sso-api/method/{id}/$attribute/metadata

Method	Desription	Payload example
PUT	Register provider metadata with SSO Server Body is JSON formatted Provider Metadata	{ "issuer":"https://oidc.provider.example.com", "authorization_endpoint":"https://oidc.provider.example.com/oidc/authorize", "token_endpoint":"https://oidc.provider.example.com/oidc/token", "jwks_uri":"https://oidc.provider.example.com/oidc/jwks", "response_types_supported":[ "code" ], "grant_types_supported":[ "authorization_code" ], "id_token_signing_alg_values_supported":[ "RS256" ], "token_endpoint_auth_methods_supported":[ "private_key_jwt" ], "scopes_supported":[ "openid" ], "claims_supported":[ "urn:oid:2.5.4.4", "urn:oid:1.2.246.575.1.14", "sub", "urn:oid:1.3.6.1.5.5.7.9.1", "urn:oid:1.2.246.21" ] }
GET	Read previously registered provider metadata Response is JSON formatted Provider Metadata
DELETE	Remove registered provider metadata Also removes JWKS and registration response

Method

Desription

Payload example

PUT

Body is JSON formatted Provider Metadata

{
   "issuer":"https://oidc.provider.example.com",
   "authorization_endpoint":"https://oidc.provider.example.com/oidc/authorize",
   "token_endpoint":"https://oidc.provider.example.com/oidc/token",
   "jwks_uri":"https://oidc.provider.example.com/oidc/jwks",
   "response_types_supported":[
      "code"
   ],
   "grant_types_supported":[
      "authorization_code"
   ],
   "id_token_signing_alg_values_supported":[
      "RS256"
   ],
   "token_endpoint_auth_methods_supported":[
      "private_key_jwt"
   ],
   "scopes_supported":[
      "openid"
   ],
   "claims_supported":[
      "urn:oid:2.5.4.4",
      "urn:oid:1.2.246.575.1.14",
      "sub",
      "urn:oid:1.3.6.1.5.5.7.9.1",
      "urn:oid:1.2.246.21"
   ]
}

GET

Read previously registered provider metadata

Response is JSON formatted Provider Metadata

DELETE

Remove registered provider metadata

Also removes JWKS and registration response

/sso-api/method/{id}/$attribute/jwks

Method	Description	Payload example
PUT	Register provider JSON Web Keys with SSO Server Body is JWKS formatted public keys (Content-Type: application/jwk-set+json)	{ "keys": [ { "kty": "RSA", "e": "AQAB", "use": "sig", "kid": "keyid9876", "alg": "RS256", "n": "05Csoq8qI...aYvRL1V_8" } ]}
GET	Read previously registered JWKS
DELETE	Remove registered JWKS

Method

Description

Payload example

PUT

Body is JWKS formatted public keys (Content-Type: application/jwk-set+json)

{ "keys": [
  {
    "kty": "RSA",
    "e": "AQAB",
    "use": "sig",
    "kid": "keyid9876",
    "alg": "RS256",
    "n": "05Csoq8qI...aYvRL1V_8"
  }
]}

GET

Read previously registered JWKS

DELETE

Remove registered JWKS

/sso-api/method/{id}/$attribute/registration

Method	Description	Payload example
GET	Generate client registration request Or read previously registered registration response Response is JSON formatted registration request
PUT	Register registration response with SSO Server Body is JSON formatted registration response	{ "redirect_uris": [ "https://sso.example.com/uas/return/oidc.aktia.1/redirect" ], "grant_types": [ "authorization_code" ], "response_types": [ "code" ], "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks", "scope": "openid scope1", "id_token_signed_response_alg": "RS256", "id_token_encrypted_response_alg": "RSA-OAEP", "id_token_encrypted_response_enc": "A128GCM", "request_object_signing_alg": "RS256", "token_endpoint_auth_method": "private_key_jwt", "client_id": "test-client", "ubisecure_request_object_query_parameters": [ "client_id", "scope", "response_type", "acr_values" ], "ubisecure_request_parameters": { "acr_values": "acr1" } }
DELETE	Remove any registration Use DELETE before GET to make sure a new registration request is generated

Method

Description

Payload example

GET

Generate client registration request

Or read previously registered registration response

Response is JSON formatted registration request

PUT

Body is JSON formatted registration response

{
    "redirect_uris": [
        "https://sso.example.com/uas/return/oidc.aktia.1/redirect"
    ],
    "grant_types": [
        "authorization_code"
    ],
    "response_types": [
        "code"
    ],
    "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks",

    "scope": "openid scope1",
    "id_token_signed_response_alg": "RS256",
    "id_token_encrypted_response_alg": "RSA-OAEP",
    "id_token_encrypted_response_enc": "A128GCM",
    "request_object_signing_alg": "RS256",
    "token_endpoint_auth_method": "private_key_jwt",
    "client_id": "test-client",
    "ubisecure_request_object_query_parameters": [
    	"client_id",
    	"scope",
    	"response_type",
    	"acr_values"
    ],
    "ubisecure_request_parameters": {
    	"acr_values": "acr1"
    }
}

DELETE

Remove any registration

Use DELETE before GET to make sure a new registration request is generated

Authentication Request

This section describes how SSO Server constructs Authorization Request from information in Provider Metadata and Registration Response.

Request parameters

Name	Description
	OAuth 2.0 parameters
`response_type`	"`code`"
`redirect_uri`	"`https://sso.example.com/uas/return/oidc.method.1/redirect`" This value must be registered with OpenID Provider
`scope`	The requested scopes as a space separated list. Should be "`openid`" if registration parameter is not defined
`state`	Random value
`client_id`	Value of registration parameter "`client_id`"
	OpenID Connect parameters
`nonce`	Random value
`prompt`	"`login`" if force-authn request is enabled "`none`" if is-passive request is enabled
`max_age`	"`0`" if force-authn request is enabled
`ui_locales`	When "`ui_locales_supported`" is a non-empty array of locale tags: Best match for SSO Server user interface locale in "`ui_locales_supported`". Value of registration parameter "`default_ui_locales`", provided it's also present in "`ui_locales_supported`". First item in "`ui_locales_supported`". When "`ui_locales_supported`" is not set: SSO Server user interface locale. Value of registration parameter "`default_ui_locales`". When "`ui_locales_supported`" is set, but is an empty array, the parameter "`ui_locales`" will not be set.
`login_hint`	Pass-thru value from authorization request
`acr_values`	Value of "`acr_values`" in the extension parameter "`ubisecure_request_parameters`" in the client metadata.

Signed request

Registration parameter "request_object_signing_alg" controls if SSO Server creates signed request. If parameter is not defined then request is not signed.

Response

Receives authorization code

Token Request

Request parameters

Name	Description
`grant_type`	"`code`"
`code`	Value from authorization response
`redirect_uri`	"`https://sso.example.com/uas/return/oidc.method.1/redirect`"

Client credentials

Registration parameter "token_endpoint_auth_method" controls what client credentials are sent with request. Default value is "client_secret_basic"

Token Validation

SSO Server attempts to choose one of the following token validation mechanisms.

ID Token

Enabled if "id_token" is present in Token Response, and if "id_token_signed_response_alg" Client Configuration value is not "none"

UserInfo

Enabled if "userinfo_endpoint" is defined in Provider Metadata..

Introspection

Enabled if "introspection_endpoint" is defined in Provider Metadata.

Configuration

Configuration strings

It is possible to configure OpenID Connect method via management UI. Following table lists, which parameters can be added info Configuration section when OpenID Connect method is selected.

Parameter	Description
`oidc.acr`	Specifies the method filtering. This can be used for filtering method visibility within application based on the received `acr_values`. One of the received `acr_values` must match with the values defined by this parameter.

Client metadata

When registering the client metadata as JSON, Ubisecure SSO provides the following extensions:

Parameter	Type	Since	Description
`ubisecure_request_object_query_parameters`	string array	8.4.1	When sending an authorization request as Request Object by Value, controls the claims that should be extracted outside of the request object and sent as HTTP query parameters.
`ubisecure_request_parameters`	object	8.4.1	Controls static parameters to be sent with authorization requests. The keys on the root level of the object will be mapped as query parameters. Values will be URL encoded. Any JSON type will be accepted and passed as an authorization request parameter
`ubisecure_request_mode`	string	8.4.1	Controls HTTP method and parameter format used for submitting the authorization request. Value `form_post` will use form encoded body and POST method. Value `query` will use query string for parameters and GET method. If not specified the default value is `query`.
`ubisecure_request_object_sub_claim_required`	boolean	8.9.3	When sending an authorization request as Request Object by Value, control if `sub` claim representing the client ID is to be added to the JWT. Default value is `false`. It is not recommended to set this value to `true` in order to avoid Cross-JWT Confusion.

An example client metadata with Ubisecure extensions:

{
  "redirect_uris": [
    "https://sso.example.com/method/redirect"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "jwks_uri": "https://sso.example.com/uas/oauth2/names/ac/oidc.method.1/metadata.jwks",
  "scope": "openid",
  "id_token_signed_response_alg": "RS256",
  "id_token_encrypted_response_alg": "RSA-OAEP",
  "id_token_encrypted_response_enc": "A128GCM",
  "request_object_signing_alg": "RS256",
  "token_endpoint_auth_method": "private_key_jwt",
  "client_id": "test-client",
  "ubisecure_request_object_query_parameters": [
      "client_id",
      "scope",
      "response_type",
      "acr_values",
      "claims"
  ],
  "ubisecure_request_parameters": {
  	"acr_values": "my-static-acr-values",
    "claims": {
      "some-complex": {
        "key": {
          "value": true
        }
      },
      "another-complex": {
        "some-key": {
          "test": true
        }
      }
    }
  }
}

This would translate to an authorization request

GET /authorization?request=eyJ...&client_id=test-client&scope=openid&response_type=code&acr_values=my-static-acr-values&claims=%7B%22some-complex%22%3A%7B%22key%22%3A%7B%22value%22%3Atrue%7D%7D%2C%22another-complex%22%3A%7B%22some-key%22%3A%7B%22test%22%3Atrue%7D%7D%7D

URL length

Please note that when sending authorization requests using GET the request URL length might exceed the limit in some browsers. Care must be taken when sending many query parameters using HTTP GET.

Compatibility flags

The following compatibility flags are supported for OpenID Connect authentication methods

Flag	Since	Applies to	Description
`StrictAudiencePolicy`	8.4.1	Specific authentication method or system-wide	Controls JWT aud claim construction and validation policy. If set, the `aud` claim is required to match the provider's invoked endpoint. If not set, accepts and generates `aud` claim with issuer, token endpoint and invoked endpoint.
`SecuredAuthorizationRequestValidate`	8.4.1	Specific authentication method or system-wide	Controls JWT claims validation of secured authorization request. If set, then implement pre 8.4.1 validation. Only `iss` claim is validated. If not set, then `aud`, `sub`, `exp` and `jti` claims are validated but only when present.
`AppleId`	8.10.0	Specific authentication method	Changes the login UI flow for showing the login popup in Safari in Apple devices to work more reliably, especially on initial authorisation request.
`FinnishTrustNetwork`	8.10.0	Specific authentication method	If set, then FTN related logic is supported. Currently, it will set `ftn_spname` authentication request parameter to value of agent friendly name (`client_name` metadata property of client (agent) application). The `client_name` property may be localized as follows: { ... "client_name":"test", "client_name#fi":"test-fi" } Note: this flag is also used in respective SAML configuration: SAML IDP Proxy - SSO

Contents

Registration

Sequence diagram

Process

1. Create OpenIDConnectMethod authentication method in SSO Server

2. Get provider metadata from your OpenID Connect provider

3. Register provider metadata with SSO Server with the metadata from issuer

4. Read jwks_uri parameter from provider metadata, and get provider JSON Web Keys

5. Register provider keys with SSO Server

6. Get registration request from SSO Server

7. Send registration request to OpenID Connect provider, and receive registration response

8. Register registration response with SSO Server

Management API endpoints

/sso-api/method/{id}/$attribute/metadata

/sso-api/method/{id}/$attribute/jwks

/sso-api/method/{id}/$attribute/registration

Authentication Request

Request parameters

OAuth 2.0 parameters

OpenID Connect parameters

Signed request

Response

Token Request

Request parameters

Client credentials

Token Validation

ID Token

UserInfo

Introspection

Configuration

Configuration strings

Client metadata

Compatibility flags

Browser not supported