Skip to main content

OpenID Connect

Introduction#

LoginID supports OpenID Connect to enable easy integrations that require very little effort. This document explains the supported features, how to get started and how to use it.

Note: the current status of this feature is alpha and is meant to provide early access while we are finalizing the implementation. Not all features are available at this point in time!

Overview#

LoginID supports OpenID Connect as an OpenID Provider (OP) and allows developers to sign up, register applications and leverage FIDO2 based strong authentication within their applications without having to implement support for FIDO2 themselves. Application users register and sign up with LoginID during the authentication and authorization flows. Developers do not have access to user details that were not exchanged during the authentication and authorization flows.

Getting started#

Leveraging LoginID's support for OpenID Connect starts off with a registration at LoginID's OpenID Connect developer dashboard. After that one or multiple applications can be registered and are usable immediately after finishing that short process. Here are a few noteworthy implementation details about supported features:

  • response_types: code
  • grant_types: authorization_code and refresh_token
  • client types: public and confidential
  • scopes: openid, email, offline_access
  • PKCE: required for public clients, using alg=S256
  • claims: sub, email, email_verified
  • token response: access_token, id_token, expires_in, token_type, refresh_token

Registering an application#

The first step is to create a developer account here: https://oauth2.sandbox-usw1.api.loginid.io:

  • Developer Dashboard
    • a FIDO2 enabled device is required (i.e.: MacBook with TouchID, Windows Hello, most Smartphones)

Next, register an application:

In the dashboard select Add Application and configure the following:

  • Application Name: a name of your choice
  • Redirect URIs: the URL to which LoginID redirects users after finishing the authorization_code flow. http may be used for localhost, otherwise https is required
  • Enable pairwise identifier: if checked, each application of the same developer will receive a different value for sub for the same application user
  • Client Type: for mobile or javascript based applications check Public. For server based web applications check Confidential. Keep it at Automatic if unsure
  • Scopes: check desired SCOPEs. email will return the users email address and if it has been confirmed. Offline access will instruct LoginID to issue a refresh_token. Tip: select the fewest SCOPE values that work for the use case
  • Links: provide the requested links if available. Both will be displayed to the user during the authorization process

Once completed, take note of the following values:

  • Client ID: use that value as the OAuth/ OpenID Connect client_id
  • OpenID configuration endpoint: copy and paste that into a browser to get a list of the OpenID configuration including the location of all endpoints. If your application supports that endpoint, configure it as openid_configuration_uri
  • Authorization endpoint: use this value or extract it from a response to the endpoint above
  • Redirect URI: your client has to use that value (or one of them if multiple were given) as its redirect_uri when initiating the authorization flow
  • Scopes: these values are the only ones LoginID will grant and only those will be displayed to application users during the authorization flow

Initializing an authorization flow#

Even though OpenID Connect capable clients are configured differently, here are a few hints to get you started more easily:

  • always URLEncode any parameter values:
    • from: https://mydomain/oauth/callback
    • to: https%3A%2F%2Fmydomain%2Foauth%2Fcallback
  • include the same redirect_uri against /authorize and /token
  • separate multiple SCOPE values by a space character [ ]

Initialize the authorization code flow

Typically, a client redirects users to the authorization endpoint like this:

  • 302
  • GET /authorize?
    • client_id={client_id}&
    • redirect_uri={redirect_uri}&
    • scope={scope}&
    • code_challenge={code_challenge_for_PKCE}&
    • code_challenge_method=S256&
    • response_type=code&
    • nonce={nonce}&
    • state={state}

Note: all values in {...} must be URLEncoded!

Once LoginID has handled the user authentication and authorization it will redirect the user back to the client.

The redirect includes either of these parameter combinations:

  • success: {redirect_uri}?code={authorization_code}&state={state}
  • error: {redirect_uri}?error={error}&error_description={error_description}
    • errors include cases where users decided not to authenticate or denied access to requested resources (scopes)

Exchange the authorization code for a token response

After receiving the authorization_code the client has to exchange it for a token response which includes an access_token and an id_token:

  • POST /token
  • Content-Type: application/x-www-form-urlencoded
  • body:
    • client_id={client_id}&
    • redirect_uri={redirect_uri}&
    • grant_type=authorization_code&
    • code={authorization_code}&
    • code_verifier={code_verifier_for_PKCE}

Note: all values in {...} must be URLEncoded!

The successful response (status: 200) will contain these values:

{
"access_token": "an-access-token",
"id_token": "id-token",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "a-refresh-token"
}

A error response (status: >= 400) will have this structure:

{
"error": "error-reason",
"error_description": "error-details"
}

Processing the token response#

Each token of the token response has a specific purpose:

  • access_token: this may be used against LoginID's /userinfo endpoint. However, the retrievable information is also included in the id_token
  • refresh_token: this is issued only if SCOPE=offline_access has been requested. It may be used to refresh an expired access_token
  • id_token: this token is expressed as a JSON Web Token and its content adheres to the OpenID Connect core specification. It represents an authenticated user

TIP: The client SHOULD validate the id_token as follows:

  • verify that aud matches the client_id
  • verify that iss matches issuer as specified in the openid-configuration
  • verify that exp is in the future
  • verify that nonce matches the value that was included in the initial authorization request
  • verify the jwt-signature
    • LoginID's /jwks may be used to retrieve the required public key
    • According to OpenID Connect core, the jwt-signature validation MAY be skipped if the id_token was received via https, directly from the issuer

Use sub of the id_token as user identifier within your application.

Use the id_token as id_token_hint on other platforms that accept a LoginID issued id_token as credential.

More information#

To get a better understanding how this feature can be used, please visit our Tutorial which leverages the OpenID Connect integration for demonstration purposes.

We can also be found on GitHub for more code examples.

For specific questions or feedback, please feel free to contact support@loginid.io!

More links#