OpenID Connect authentication method - SSO
- ubisebastian
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.
Contents
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:
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:
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:
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.
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.
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.
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 |
/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": {
"keys": [
{
"kty": "RSA",
"n": "wzvEi05...WU-XSJTdw",
"e": "AQAB"
}
]
},
"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 | " This value must be registered with OpenID Provider |
scope | The requested scopes as a space separated list. Should be " |
state | Random value |
client_id | Value of registration parameter " |
OpenID Connect parameters | |
nonce | Random value |
prompt | " " |
max_age | "0" if force-authn request is enabled |
ui_locales | When "
When "
When " |
login_hint | Pass-thru value from authorization request |
acr_values | Value of " |
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.
See also Signed and encrypted request - SSO
Response
Receives authorization code
Token Request
Request parameters
| Name | Description |
|---|---|
grant_type | "code" |
code | Value from authorization response |
redirect_uri | " |
Client credentials
Registration parameter "token_endpoint_auth_method" controls what client credentials are sent with request. Default value is "client_secret_basic"
See also Client credentials - SSO
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 |
|---|---|
| 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 |
|---|---|---|---|
| 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. |
An example client metadata with Ubisecure extensions:
{
"redirect_uris": [
"https://sso.example.com/method/redirect"
],
"grant_types": [
"authorization_code"
],
"response_types": [
"code"
],
"jwks": {
"keys": [
{
"kid": "dDRiW2EFbhJs_GKIH20MIOdRjt0",
"kty": "RSA",
"n": ...
"e": "AQAB"
}
]
},
"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 |
|---|---|---|---|
| 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. |
| 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. |