Note
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

...

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

...

Code Block

collapse

title	Request example		true

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

...

Code Block

title	Response example	collapse	true

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"
        ]
    }
}

...

Code Block

title	Request example	collapse	true

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"
   ]
}

...

Code Block

title	Example response	collapse	true

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"
   ]
}

...

Code Block

title	Example request	collapse	true

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"
  }
]}

...

Code Block

collapse

title	Example response		true

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"
  }
]}

...

Code Block

title	Example response	collapse	true

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.

Info

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.

Code Block

collapse

title	Example of manually edited registration request		true

{
    "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"
            }
        ]
    }
}

...

Code Block

title	Example request	collapse	true

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"
    }
}

...

Code Block

title	Example response	collapse	true

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"
    }
}

...

/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

/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

...

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.

...

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..

...

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.

...

Warning

title	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

...

Versions Compared

Old Version 8

New Version Current

Key

Contents

Registration

Sequence diagram

1. Create OpenIDConnectMethod authentication method in SSO Server

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

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

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

OAuth 2.0 parameters

OpenID Connect parameters

UserInfo

Compatibility flags

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Contents

Registration

Sequence diagram

1. Create OpenIDConnectMethod authentication method in SSO Server

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

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

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

OAuth 2.0 parameters

OpenID Connect parameters

UserInfo

Compatibility flags