Singpass Login API Integration-part 1

This article provides overview and authentication flow details of Open ID connect (OIDC) and brief overview of Singpass an OIDC provider.

OIDC Overview

OpenID Connect (OIDC) is an authentication protocol that adds identity layer on top of Oauth 2.0 protocol.

In order to understand this consider a simple example of login/signup to Medium using Login with Google option. This process includes following steps which uses OIDC flow:

• Login with Google
• If you are not signed-in to your Google account you will be redirected to login to your Google account
• Once successfully logged-in you will be prompted with following confirmation message to allow Medium to access your basic profile and email ID

To continue, Google will share your name, email address, language preference and profile picture with Medium. Before using this app, you can review Medium’s privacy policy and Terms of Service

• Thus Medium uses these profile details and creates a new account for the user

OIDC Actors

Figure: OIDC Actors

OIDC flow includes 5 main actors as shown above. Each of these are described in detail below.

1. Resource Owner:

• The resource owner is a person who owns the data on resource server.
• For instance in above example, application user i.e. you are the resource owner.

2. User Agent:

• The user agent is any web browser or mobile application which sets up communication between OIDC provider and relying party (client).
• For instance in above example, web browser application used acts as a user agent in OIDC flow.

3. Relying Party:

• Relying party also known as client is an entity that requires access to resource owner’s data.
• For instance in above example, Medium is the relying party that is trying to access data on your behalf.

4. OIDC Provider (OP):

• OIDC Provider (OP) is an authorization server that accepts authorization requests and authenticates the user by providing requested resource.
• For instance in above example, Google is the OIDC provider that provides user’s profile information.

5. Resource Server:

• Resource server is an API or a service the client uses on resource owner’s behalf to access his basic information.
• For instance in above example, Google’s profile resource service is used to fetch user’s basic profile.

Terminology

Here are some terminologies used in OIDC flow.

• Client ID: Client ID refers to unique ID given by OIDC providers which allows them to identify authorized clients.
• Redirect URI: Redirect URI also known as callback URL is used by OIDC provider to redirect resource owner back to the application once he authorizes client application.
• Authorization code: Authorization code is given by OIDC providers which can be exchanged for access token and ID token.
• Grant type: Grant type refers to the way in which client application receives authorization code. One of the grant type used is Authorization Code in which OIDC provider sends authorization code on relying party’s backend server (also known as back channel).
• Response type: Response type refers to the type of information client application expects. Most common response type used is Code which indicates that application expects to receive authorization code after successful authorization.
• Scope: Scope specify access privileges used while issuing access token. Privileges refers to data access or actions client application needs to perform on resource owners data. openid scope is required by client to work with OIDC.
• Token: OIDC providers issues JSON web tokens (JWTs) which can be obtained from OIDC flow. Below 2 tokens are issued during OIDC flow.
  1. Access Token: Refers to key which is used to access or perform actions on resource(data) from resource server.
  2. ID Token: OIDC provider issues ID token which contains resource owner’s encoded basic profile information.

OIDC Flow

Figure: OIDC Flow

Above figure illustrates OIDC flow, each step is described in detail below.

1. Resource owner wants to allow client to access basic profile so that client can create an account.
2. The client redirects the user agent to authorization server , it includes with the request the Client ID, Redirect URI, Response Type and Scope.
3. Authorization server checks if resource owner is already logged in and if not then presents him with prompt to log in.
4. Also authorization server prompts user to allow client application to access user’s data.
5. Once resource owner authorizes the client application the authorization server redirects back to client using the redirect URI with an authorization code.
6. Authorization code obtained in previous step is used to exchange with access token and includes with request the client ID, secret and authorization code.
7. Client application retrieves profile information from the token and uses this profile information to create an account with the client application.

OIDC Providers

Singpass is an OIDC provider which can be integrated to add authentication layer to mobile and web applications. Singpass Login API allows citizens to access digital services by logging in with their Singpass app thus eliminating need for username/password for accessing digital services.

Detailed explanation of Singpass OIDC flow and Singpass integration details can be found in next Singpass Login API Integration-part 2 article.