Skip to main content

Implement with OIDC

This guide shows you how to implement a connection with OpenID Connect (OIDC) for SIAM.

Before you begin

Before starting your OIDC integration, ensure to complete the steps to Configure SIAM.

Add an OIDC client​

An OIDC client allows your application to authenticate users with SIAM using standardised, secure OAuth 2.0 protocols.

When you register an OIDC client application, you receive a client ID. To do this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
  2. Select Create/Add client.
  3. Enter a name for the client.
  4. In Primary grant type, select the grant type (authentication flow) to use for this client.
    Choosing a grant type

    The Authorization Code flow is recommended for most cases. Learn more about supported flows in the generic OIDC implementation guide and the OAuth 2.0 specification.

  5. In the Redirect URI field, enter the URL where to redirect the end-user after authentication. You can always edit and add more URIs later.
  1. In the Scope field, enter the scopes you want for this client. openid is mandatory. Find out what scopes are supported in the Attributes reference.
    OIDC scope configuration

    Scopes encode what personal information you request from your end-users. You can retrieve the custom attributes you define in your SIAM platform by specifying the ownidp-extra scope in your request.

  2. Select Create to create the OIDC client.

Add a client secret​

Depending on the type of your application, you may want to add a client secret. To do this:

  1. In the menu for the client, go to the Secrets tab and select Add secret.
  2. Enter a name for your client secret and select Create.
  3. Copy your new client secret and store it safely.
Important

Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one.

PKCE

We strongly recommend using PKCE, even when you are using a client secret. Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE).

Learn more about PKCE in the eID and Wallet Hub documentation.

OIDC authentication flow​

An authentication flow with OIDC typically involves the following steps:

  1. You build the authentication request with the appropriate parameters.
  2. Redirect the user to the authorization endpoint.
  3. User authenticates with SIAM.
  4. After successful authentication, the provider sends the user to the Redirect URI.
  5. At the same time, your application receives the authorization code and the state.
  6. Your backend exchanges the code for tokens: ID token, access token and refresh token (optional).
  7. You validate the ID token before establishing a session.
  8. Optionally, you retrieve additional information through the userInfo endpoint.

Below, you find instructions to complete an authentication flow with SIAM.

Build the authentication request​

To begin an authentication flow, design your application to build an authentication URI which points to the authorization (authorize) endpoint. Then, you direct the end-user to the authentication URI in a browser, where they can log in with their SIAM credentials.

Your application should send an HTTPS GET request with the appropriate URI parameters. Here is an example of an authentication URI with OIDC:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
    &client_id=<OIDC_CLIENT_ID>
    &response_type=code
    &redirect_uri=<REDIRECT_URI>
    &state=xyz123
    &scope=openid%20profile%20address%20phone%20nin%20ownidp-extra
    &acr_values=idp:ownidp
    &prompt=login
    &code_challenge=Qr_Nb4Ge6pPGzGW5pMThE8QSHzhP432v4NfIgeNFylI
    &code_challenge_method=S256
Authorisation endpoint

You can find the base URL of your authorization_endpoint in the discovery document of your OIDC client available in the Signicat Dashboard under "Well-Known URL for client".

The above example uses the following parameters:

  • client_id: The OIDC client you created in the Signicat Dashboard.
  • response_type: The grant type (flow). For the authorization code flow, use code.
  • redirect_uri: The Redirect URI where to send the end-user after authentication.
  • state A random string to prevent cross-site request forgery (CSRF). Verify it when the user is redirected back to your app.
  • scope: A space-delimited list of scopes to indicate what personal data to request. Find out what scopes are supported with SIAM in the Attributes reference.
  • acr_values: Establishes the identity provider (IDP) routing. For SIAM, idp:ownidp routes the end-user directly to your SIAM platform, skipping the eID selection screen.
  • prompt=login: Optional. Forces the login screen to be shown, even if the user is already authenticated.
  • code_challenge_method=S256: Specifies the method used to derive the code challenge for PKCE.
  • code_challenge: The code challenge used for PKCE.

You can find additional authentication request query parameters in the OIDC specification.

Important

The values you specify in the query parameters must match the values you configured for your OIDC client in the Dashboard.

End-user authentication​

To authenticate with SIAM, end-users must enter their credentials on the SIAM login page and consent to share their personal data with you in the confirmation screen.

After successful authentication, the authorization server redirects the end-user back to the redirect_uri you specified in the authentication request. The response message contains the authorization code and state in the query string.

Server response​

Now, you can retrieve the end-user data by exchanging the authorization code in the server response for an access token that includes the ID token.

Example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>?
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
&scope=openid%20profile%20address%20phone%20nin%20ownidp-extra
&state=xyz123

You should check that the state in the redirect matches the original state sent in the authentication request to mitigate CSRF and other related attacks.

The code holds the authorization code generated by the authorization server. You use this code in the request to the token endpoint to obtain an access token and the ID token.

Obtain the access token​

You can now exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the token endpoint of the authorization server.

Example token request

POST /auth/open/connect/token HTTP/1.1
Host: <YOUR_SIGNICAT_DOMAIN>
Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
redirect_uri=<REDIRECT_URI>
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
code_verifier=oQDZ3uPQn...W7U

Example token response

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

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

ID token​

An ID token is a JWT that contains information about the authenticated user.

Decoded payload (data) of the ID token for SIAM:

{
    "iss":"https://<ACCOUNT_DOMAIN>/auth/open",
    "nbf":1726046529,
    "iat":1726046529,
    "exp":1726047129,
    "aud":"<OIDC_CLIENT_ID>",
    "amr":[
        "external"
    ],
    "at_hash":"_T539pqKJTOovx1xVyMnKA",
    "sid":"783EFB56CEE40C1FA95F0543535B6E4E",
    "sub":"X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=",
    "auth_time":1726046523,
    "idp":"ownidp",
    "sandbox":true
}
ID Token

By default, the ID Token returns only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, go to your OIDC client configuration in the Signicat Dashboard and edit the ID Token User data in the Advanced > Security tab to return All claims.

UserInfo response​

You can retrieve full user information by making a request to the UserInfo endpoint using the access_token as a Bearer token.

Example response from the UserInfo endpoint:

{
    "sub": "X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=",
    "name": "John Robert Doe",
    "family_name": "Doe",
    "given_name": "John",
    "middle_name": "Robert",
    "gender": "male",
    "birthdate": "1985-06-15",
    "company": "Signicat AS",
    "phone_number": "+4799999999",
    "address":
    {
        "formatted": "Munkegata 26B, 7011 Trondheim, Norway",
        "street_address": "Munkegata 26B",
        "locality": "Trondheim",
        "region": "Trøndelag",
        "postal_code": "7011",
        "country": "Norway"
    },
    "nin": "15068512345",
    "nin_type": "social_security_number",
    "nin_issuing_country": "NO",
    "custom_member_id": "M12345",
    "custom_tier": "Gold",
    "preferred_theme": "dark"
}

SIAM OIDC claims​

See the OIDC parameters that apply to SIAM:

Attributes reference
Attributes and claims for SIAM with OIDC
On this page