Skip to main content

OIDC implementation

Flows​

OpenID Connect (OIDC) lets developers authenticate users across websites and apps without having to own and manage password files. Authentication can be done in three different ways using OIDC:

  • The authorization code flow
  • The implicit flow
  • The hybrid flow

We have implemented two of them, the authorization code flow and the hybrid flow. These flows will be the ones described in this document. To learn more about the different flows and their differences, refer to the OIDC documentation.

Authorization code flow​

The authorization code flow provides you with an authorization code. You can exchange the authorization code for an ID token, an access token and a refresh token (optional) at the token endpoint of our OIDC server.

This process provides the benefit of not exposing any tokens to the user agent (and possibly other malicious applications with access to the user agent). For the authentication server to trust the client before exchanging any authentication data regarding the end-user, the server can authenticate the client. The authentication code flow is therefore suitable for clients that can securely maintain a client secret between themselves and the OIDC authentication server.

The authorization code flow steps for performing authentication to log in the end-user (or to determine that the end-user is already logged in) are as follows:

  1. The user agent requests to be authenticated.
  2. The client prepares an authentication request and sends the request to the OIDC server.
  3. The authorisation server authenticates the end-user.
  4. The authorisation grant code is requested.
  5. The OIDC server obtains end-user consent (optional).
    1. If consent is asked for but denied, the end-user will not be authorised and will not be able to access their resources. The login will be stopped. The process will end at this step.
    2. If consent is asked for and given, the end-user will be authorised. The process continues with step 6.
  6. The OIDC server sends the end-user back to the client with an authorization code.
  7. The client requests a response using the authorization code at the token endpoint of our OIDC server.
  8. The client receives a response that contains an ID token, an access token and a refresh token (optional) in the response body (among other parameters).
  9. The client validates the ID token, retrieves the end-user's subject identifier and requests resources.

Hybrid flow​

The hybrid flow combines the implicit flow with the authorization code flow. With the hybrid flow, some tokens are returned from the authorization endpoint and others are returned from the token endpoint.

Here's a brief summary of how the hybrid flow works:

  1. The user agent requests resources.
  2. The client prepares an authentication request and sends it to the OIDC server.
  3. The authorisation server authenticates the end-user.
  4. The authorisation grant code is requested.
  5. The OIDC server obtains end-user consent.
  6. The authorisation server sends the end-user back to the client with an authorization code and, depending on the response type, one or more additional parameters.
  7. The client requests a response using the authorization code at the token endpoint of our OIDC server.
  8. The client receives a response that contains an ID token and an access token in the response body (among other parameters).
  9. The client validates the ID token and retrieves the end-user's subject identifier.

Claims​

At the heart of OIDC are claims - an attempt to standardise all the different units of information about an end-user. A claim may, for instance, be an end-user's surname or email address. Claims are similar to the concept of assertions in SAML, though claims in OIDC are represented (as everything else in OAuth 2.0/OIDC) as JSON key-value pairs.

Where to get claims?

The OIDC specification details two sources of claims:

  • The ID token
  • The UserInfo endpoint

The ID token is a signed JSON object (a JSON web token, or JWT) containing the authentication result. You can learn more about the ID token in the OIDC documentation. Some claims in the ID token are optional and can be left out depending on how much information you want it to contain.

The UserInfo endpoint is a separate endpoint that accepts access tokens and returns information about the end-user. An access token represents an authorisation from the end-user to the client to perform actions on the end-user's behalf. Therefore, only information that the end-user has authorised should be returned. The UserInfo claims that can be returned are largely standardised but can be infinitely extended.

Note

We strongly recommend that you use only the ID token for obtaining claims. Using UserInfo usually adds complexity for very little benefit.

Signing keys​

The signing key is a JSON web key (JWK) which contains the public part of an asymmetrical key pair. In general terms, a JWK is a JSON object that represents a cryptographic key.

Signing keys ("use": "sig") are published through JSON web key set (JWKS), a well-known URL available at your Signicat domain. Signicat signs each token with the private key on the authorisation server side.

To verify that a JWT token is valid and originated from the Signicat authorisation server, your application needs to verify the token's signature using the public key published in the JWKS. Signature validation ensures that the token was issued by Signicat and that no one has tampered with the token.

JSON web key set (JWKS)​

A JSON web key set (JWKS) contains a set of keys containing the public keys that your application can use to validate any Signicat-issued token (JWT), like access and ID tokens.

Note that while the JWKS may contain multiple keys, your application needs to use only one JWK to validate the token's signature.

The JWKS is available at a public endpoint in your Signicat domain. To find your JWKS endpoint:

  1. Go to https://<YOUR_SIGNICAT_DOMAIN>/auth/open/.well-known/openid-configuration.
  2. Locate the endpoint specified in the jwks_uri field.
  3. Go to the JWKS (jwks_uri) endpoint.

The JWKS endpoint contains a JSON with a list of keys for both:

  • Production signing keys
  • Sandbox signing keys
Sandbox signing keys

Sandbox keys are prefixed with “sandbox-”. For example, "kid": "sandbox-signing-key-...".

Learn more about JWK parameters in the RFC 7517 Internet Standards.

Key rotation​

It is important to assume that the JWKS endpoint could contain several JWKs at any given time. In fact, an undetermined number of unordered keys are usually available for you to fetch at the JWKS endpoint. The keys in the key set are subject to change because of key rotation. In fact, periodic key rotation is best practice and ensures a higher level of security.

When validating a token consider the following:

  • If token signature validation fails, fetching the current key set returns a set where one of the keys is the correct one.
  • New keys for token signing are published to the JWKS endpoint before we change the key used for signing. This is to allow enough time for your caching processes to prefetch the newly updated key set.

Signicat recommends you refresh your replica, or cache, of signing keys regularly. Note that we rotate keys frequently. For instance, you could refresh your cache whenever a kid (key identifier) is present in the JWKS but not present in your cache. Vice versa, you may remove a key with a kid present on your side but not in the JWKS.

Default signing and encryption​

  • Encryption algorithm: AES-128
  • Supported key length: 2048-bit (4069-bit also supported)
  • Signature hash: SHA-256
What?SigningEncryption
ID tokenAlwaysOptional, off by default
Access tokenAlwaysNever
UserInfo responseOptional, off by defaultOptional, off by default
Note

Elliptic curve cryptography (ECC) key pairs are not supported at the moment. If your implementation requires this feature, you need to contact us by creating a support ticket in the Signicat Dashboard.

Endpoints​

The following endpoint URLs are available for communicating with the OpenID Connect provider through Signicat.

Authorization​

The authorization endpoint performs the authentication of the end-user. You can find the full list of available request parameters in the 'Authentication Request' section of the OIDC documentation.

Example authorization request

"https://<YOUR SIGNICAT DOMAIN>/auth/open/connect/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=openid%20profile&state=123&code_challenge=ABC123&code_challenge_method=S256&response_mode=query"

acr_values​

You can use acr_values to adjust how the authentication flow behaves. There are generic parameters (listed below) that apply to all identity providers (IdPs), as well as IdP-specific parameters.

The format of the parameter is a space-separated list of key-value pairs: acr_values=key1:value1 key2:value2. To specify multiple values for the same key, use the comma-separated format: acr_values=key1:value1a,value1b.

Example: acr_values=idp:idp_name,other_idp_name loa:high

Result: IdP will be pre-selected for the end-user; Level of Assurance is set to high.

Available parameters:

NameDescription
idpDefines which IdP to use. This works in conjunction with login_hint.
loaSpecifies the eIDAS Level of Assurance (LoA). Allowed values: low, substantial or high.
themeSpecifies which theme to use.
Set acr_values at the client level​

Typically, you define acr_values as a query parameter in your authorization request. However, you can also configure ACR values at the client level, thus applying specific values to all the requests by default without the need to define acr_values explicitly for each request.

You can configure default acr_values in your OIDC client in the Signicat Dashboard. To do this:

  1. Go to your OIDC client in the Dashboard.
  2. Choose your OIDC client and select Edit.
  3. Navigate to the Access tab, then edit the ACR values field with the values you want to use by default in all requests.
  4. Optional. Tick the Force use ACR values box to prevent that ACR values are overridden or changed when defined as query parameters in a request.

Any ACR values you configure in the Dashboard apply now to all authentication flows by default.

Note that passing acr_values as a query parameter in the request overrides the default values you configure in the client in the Dashboard, unless you force the use of ACR values.

login_hint​

You can use this login_hint to prefill end-user information that we send to the IdP, such as the end-user's national identification number. The format is a space-separated list of key-value pairs: login_hint=key1:value1 key2:value2, and so on.

The following options are available:

NameDescription
ninPrefilled National identification number.
mobilePrefilled mobile phone number.
dateOfBirthPrefilled date of birth (YYYY-MM-DD).
emailPrefilled email address.
usernamePrefilled username information.

You can find specific configuration examples for the following ID methods here:

login_hint and acr_values field format

Note that query parameters must be URL encoded (percent encoding).

For example, if you want to prefill end-user mobile numbers with login_hint, use login_hint=mobile:%2B447700900000 to represent the +44 7700900000 phone number.

Token​

To obtain an access token, an ID token and optionally a refresh token, the client sends a token request to the token endpoint to obtain a token response.

Example token request

curl -XPOST "https://<YOUR SIGNICAT DOMAIN>/auth/open/connect/token" -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic czZCaGRSa3FOMzpnWDFmQmFOM2JW" -d "grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://example.com"

Example token response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5"
    "token_type": "Bearer",
    "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g",
    "expires_in": 3600,
    "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg"
}​

UserInfo​

To obtain the requested claims from the UserInfo endpoint, the client makes a request using an access token obtained through OpenID Connect authentication.

Example UserInfo request

curl -XPOST "https://<YOUR SIGNICAT DOMAIN>/auth/open/connect/userinfo" -H "Accept: application/json" -H "Authorization: Bearer fAAdL01c6QWDbPs9HrWHz5e7nRWVAnxqTTP7i88G"

Example UserInfo response for valid access token

HTTP/1.1200OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "sub": "bob"
    "given_name": "Bob",
    "name": "Bob Smith",
    "email": "bob@mycompany.com",
    "phone_number": "+1 (604) 55-555-66-777",
    "address": {"formatted": "123 Main St., Anytown, TX 77777"},
}

IdP discovery​

If you have more than one ID method configured in your Signicat account, you can use IdP discovery to route the end-user to a specific ID method for authentication, therefore skipping the ID method selection screen where typically the end-user can choose their preferred ID method (from all the methods active in your account). This feature is also known as IdP scoping or IdP routing rules.

With IdP discovery, you can define logic to determine two aspects of an authentication flow:

  • ID method discovery: You can define which ID method to use, such as iDIN or Norwegian BankID.
  • Provider discovery: You can specify the entity or provider (such as a bank) for an ID method. For example, for iDIN you can choose to route end-user only to one of the banks. Note that this functionality is limited to certain ID methods only.

ID method discovery​

To control which ID method to display to your end-users, you can use the idp key of the acr_values query parameter with the format acr_values=idp:idp_name,other_idp_name.

You can find an overview of the values for each ID method at https://<YOUR_ACCOUNT_DOMAIN>/broker/idps. Use the value of internalName.

If you define only one ID method in the query parameter, the end-user is routed to the IdP-specific authentication page, automatically skipping the IdP selection screen during authentication.

For example, to direct the end-user to SMS OTP, thus skipping the ID methods selection screen, use acr_values=idp:otp-sms. This prevents users from choosing other ID methods that may be active in your account.

How to display a subset of ID methods

To let the end-user choose among a subset of ID methods active in your account, specify multiple values in the idp key (comma-separated format). For example, use acr_values=idp:otp-email,ftn to display Email OTP and FTN to the end-user in the ID method selection screen.

To learn more about acr_values, see the acr_values section above.

Restrict IdPs in the Dashboard​

In some cases, you may want to limit the number of ID methods available for a specific OIDC client. For example, when you use several OIDC clients for different purposes and applications.

You can restrict the ID methods available for your OIDC client in the Signicat Dashboard. To do this:

  1. Go to your OIDC client in the Dashboard.
  2. Choose your OIDC client and select Edit.
  3. Navigate to the Access tab, then enter the ID methods in the Identity provider restrictions field.

Now, only the specified IdPs are available for the OIDC client. The restriction applies to all authentication requests to Signicat using this OIDC client.

Provider discovery​

Certain ID methods are comprised of a network of identity providers (or issuers), such as banks, that collectively offer authentication to their customers. You may want to offer your end-users only a limited number of these providers when the end-users authenticate with an ID method.

To control which providers you make available for each authentication session, you specify a field in the acr_values in your authorization request.

Below, you can find an overview of the available parameters for each ID method:

ID methodACR keyProviders
iDINidin_idpView the list of iDIN issuers (banks) active in your account at https://<YOUR_ACCOUNT_DOMAIN>.com/broker/authn/idin/issuers, where <YOUR_ACCOUNT_DOMAIN> is the domain you registered in the Signicat Dashboard Domain management.
FTNftn_idpView the list of FTN issuers in the ID method documentation for FTN.

For example, when authenticating end-users with the Finnish Trust Network (FTN), you can specify FTN providers with the ftn_idp parameter in the ACR values. To make available for authentication only Aktia Bank, pass the following query parameter in your authorization request:

acr_values=ftn_idp:fi-aktia

You can find more details for each ID method in the respective ID method documentation.

Error codes​

We follow the OIDC and OAuth standards as closely as possible, which is also true when conveying error messages.

Errors on the authorization endpoint are primarily passed along as parameters on the redirect URI. These URL parameters are error and error_description. You can see a list of the Signicat-specific error codes here.

In some situations, it's not possible to use the redirect URI to pass along errors. In these cases, we display an error page. These types of errors are typically the result of an incorrect implementation or invalid configuration. These errors are typically not caused by the end-users.

Errors from the token and UserInfo endpoints are strictly defined in the OpenID Connect and OAuth protocol specifications:

  1. Token error response
  2. UserInfo error

Finally, there are standard HTTP status error codes that can, for instance, appear if there is a serious error in the solution (typically a 5xx server error) or if you are trying to access an incorrect URL (404). These will be what you would expect from any web service or API.

Single sign-on (SSO)​

Single sign-on (SSO) allows the end-user to establish their identity once without having to re-authenticate every time they access your services.

Levels of SSO

Signicat eID Hub supports two levels of SSO, at the OIDC server and Broker level.

This page describes only SSO at the OIDC server level. More information about SSO at the Broker level will follow soon.

How it works​

When the end-user first logs in with SSO, the Signicat OIDC server sets, and stores, an encrypted cookie that contains information about the end-user's device. Note that the SSO scope is set at the (Signicat) account level.

On subsequent logins, the Signicat OIDC server checks to see whether there is an existing SSO cookie. The SSO cookie validity and lifetime are verified on Signicat's backend side.

If a valid cookie is present, the end-user is automatically redirected to your application without being asked to re-authenticate.

SSO in the Dashboard​

When you create a new OIDC client, SSO is enabled by default.

You can control the cookie lifetime with the User SSO lifetime setting. The default value is 3600 seconds (1 hour).

To change the SSO session lifetime:

  1. Go to your OIDC client in the Dashboard and select Edit to view the client configuration.
  2. Navigate to the Advanced > Lifetimes tab.
  3. Edit the User SSO lifetime setting.
  4. Select Update to save and apply the changes.

Forcing re-authentication​

To force the end-user to re-authenticate every single time, use the URL parameter prompt=login in each authorisation request.

Maximum Authentication Age (max_age=0)

When forcing re-authentication, avoid using max_age=0 as an alternative to prompt=login.

Single log-out (SLO)​

Single log-out (SLO) is a feature that allows the end-user to sign out of multiple authenticated sessions with a single action.

Signicat implements the OpenID Connect RP-Initiated Logout 1.0 standard for end-user logout.

OIDC level only

At the moment, the end-user will only be logged out of Signicat OIDC server. Any other potential SSO session at the application, IdP or Broker level will not be terminated (logout).

Example of logout​

To initiate logout you need to direct the end-user to the /auth/open/connect/endsession endpoint, as shown in the following example:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/endsession?post_logout_redirect_uri=https://signicat.com&id_token_hint=eyJhb...QifQ...hLVNI8Q

You can customise the logout process by specifying the following query parameters:

  • id_token_hint (recommended). It's necessary to identify the end-user you want to log out. It should contain a valid ID Token as described in the next section.
  • post_logout_redirect_uri (optional). The URI you provide in the request must match the URI configured in the Post Logout Redirect URI setting of your OIDC client in the Dashboard.

Providing an ID token​

If you initiate a logout request without providing a valid ID token the end-user will be presented with a web page that prompts them to log out, instead of automatically logging them out.

The ID token provides the context necessary to log out the end-user in an automated way. Without this information, it is not possible to link the client and the end-user logout request. Therefore, without a valid ID token the end-user has to submit their consent to log out.

This also means you cannot use Post Logout Redirect URI or Automatic Redirect to Logout Url functionality.

Automatic redirect after logout​

After the end-user logs out, you can automatically redirect the end-user to a specific URL. You can control where to redirect the end-user with the Post Logout Redirect URI setting.

For security reasons, you need to meet the following conditions:

  • Provide valid id_token_hint and post_logout_redirect_uri in the request.
  • Enable Automatic Redirect to Logout Url in the URIs configuration of your OIDC client in the Dashboard.

Without these conditions the end-user gets redirected to a default confirmation logout screen.

Finnish Trust Network (FTN) specifics​

Due to requirements from Traficom, you are required to use Full Message-Level Encryption (MLE) for authentication with FTN.

There are two different ways to achieve this. The first is required and the second is only required in certain circumstances:

  1. Receiving encrypted responses from Signicat (required)
  2. Sending encrypted requests to Signicat (optional)
Important

If you are sending personally identifiable information (PII) as part of your request, you will also need to send encrypted requests.

Both these mechanisms are described in Advanced security considerations.

External references​

OpenID Connect​

OAuth 2.0​

Last updated: