# Understanding the Basics

This guide demonstrates how to integrate with Singpass and display user profile information after the authentication and authorization process.

Check out our [demo app](https://singpassdemoapp.netlify.app/) to experience the login flow for yourself or refer to the interactive demo below for the outcome of this integration guide.

{% @guideflow/guideflow-embed requestedUrl="<https://app.guideflow.com/player/dkd3zejt9p>" %}

## Singpass Endpoints

Singpass uses two endpoints for the authentication and authorization process.

<figure><img src="https://4078627714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIQVffPvHpumbSBzjD6fZ%2Fuploads%2FS2T9nVeJ6SsW4oPi4CkM%2FOIDC%20Endpoint.png?alt=media&#x26;token=56a1e3cb-4e80-4507-a530-14c9d9c52a20" alt=""><figcaption><p>Singpass Endpoints</p></figcaption></figure>

## Discovery Endpoint

This endpoint provides information about Singpass's endpoints and other configuration details.&#x20;

## Authorization Endpoint

This is the only endpoint where Singpass will interact with the users and get their authorization. Singpass will then return the authorization code in response via this endpoint.

## Token Endpoint

This is the endpoint where Singpass will exchange the code received from the authorization endpoint for an ID Token and access token. Singpass only supports confidential clients, hence every application is required to authenticate at the token endpoint using a [client ID](https://ndi-px.gitbook.io/singpassdevdocs/getting-started/custom-integration/demo-application-setup) and [JWT Assertion](https://ndi-px.gitbook.io/singpassdevdocs/getting-started/custom-integration/setup-client-assertion).

### **Information Exchanged during Federated Authentication Flow**

This section provides a high-level overview of the attributes and details that are exchanged during the federated authentication flow. This section aims to highlight the key attributes/information exchange during Singpass authentication. Details for each request parameter will be explained later in each integration step.

<table><thead><tr><th width="266">Endpoints</th><th>Request Parameters</th><th>Response Parameters</th></tr></thead><tbody><tr><td><strong>Authorization Endpoint</strong></td><td><p></p><ul><li><code>client_id</code></li><li><code>redirect_uri</code></li><li><code>response_type</code></li><li><code>state</code></li><li><code>nonce</code></li><li><code>scope</code></li></ul></td><td><p></p><ul><li><mark style="color:blue;"><strong><code>code</code></strong></mark><strong>:</strong> A 60-digit random string known as authorization code that is to be exchanged when calling token endpoint</li><li><mark style="color:blue;"><strong><code>state</code></strong></mark><strong>:</strong> Same state parameter sent in the request parameter will be returned back </li></ul></td></tr><tr><td><strong>Token Endpoint</strong> </td><td><ul><li><code>authorization code</code> </li><li><code>redirect_uri</code></li><li><code>response_type</code></li><li><code>client_id</code></li><li><code>JWT Assertion</code></li></ul><p><br></p></td><td><p></p><ul><li><mark style="color:blue;"><strong><code>access_token</code></strong></mark><strong>:</strong>A non-usable random string known as access token</li><li><mark style="color:blue;"><strong><code>id_token</code></strong></mark><strong>:</strong>A signed and encrypted JWT containing user’s identity and other standard claims explained in the next section</li></ul></td></tr></tbody></table>

## Singpass ID Token Claims

<mark style="color:blue;">**`Claims`**</mark> are name/value pairs that contain information about a user, as well as meta-information about the OIDC service. The following are the details of the set of Claims (the JWT Claims Set) returned in the ID Token sent by Singpass.

{% hint style="info" %}
The format and structure of the issued ID Token from the Token Endpoint will vary depending on whether the client’s profile required is UUID only or both NRIC and UUID
{% endhint %}

### Client Profile Types

In OpenID Connect (OIDC), a client profile refers to the configuration and settings associated with a particular client application that interacts with an OIDC provider. Depending on the client profile, the details of the claim content returned by the token endpoint will differ.

| Client Profile                                        | Sub Claim Content                                                                                                                                         |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">`direct`</mark>             | <p><mark style="color:blue;"><strong><code>UUID Only</code></strong></mark><br><br>Example:<br>u=32af8b7d-ad1d-4c25-8dc7-0a981b533000</p>                 |
| <mark style="color:blue;">`direct_pii_allowed`</mark> | <p><mark style="color:blue;"><strong><code>NRIC and UUID</code></strong></mark><br><br>Example:<br>s=S1234567A,u=32af8b7d-ad1d-4c25-8dc7-0a981b533000</p> |

Details of ID token claims are shown below:

<table><thead><tr><th width="143">Claim</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:blue;"><code>sub</code></mark></td><td>The principal that is the subject of the JWT. Contains a key value mapping that identifies that user of the token. For clients with profile <mark style="color:blue;"><strong><code>direct</code></strong></mark>, the expected format is u=userId. For other clients, the expected format is s=NRIC,u=userId. <a href="https://tools.ietf.org/html/rfc7519#section-4.1.2">Ref.</a></td></tr><tr><td><mark style="color:blue;"><code>aud</code></mark></td><td>The client_id of the relying party. <a href="https://tools.ietf.org/html/rfc7519#section-4.1.3">Ref.</a></td></tr><tr><td><mark style="color:blue;"><code>iss</code></mark></td><td>The principal that issued the JWT. <a href="https://tools.ietf.org/html/rfc7519#section-4.1.1">Ref.</a></td></tr><tr><td><mark style="color:blue;"><code>iat</code></mark></td><td>The time at which the JWT was issued. <a href="https://tools.ietf.org/html/rfc7519#section-4.1.6">Ref.</a></td></tr><tr><td><mark style="color:blue;"><code>exp</code></mark></td><td>The expiration time on or after which the JWT MUST NOT be accepted for processing. Defaults to 10 minutes since "iat". <a href="https://tools.ietf.org/html/rfc7519#section-4.1.4">Ref.</a></td></tr><tr><td><mark style="color:blue;"><code>nonce</code></mark></td><td>A string that uniquely identifies the authentication.</td></tr><tr><td><mark style="color:blue;"><code>amr</code></mark></td><td><p>Authentication Methods References <a href="https://tools.ietf.org/html/rfc8176">RFC 8176</a>. JSON array of strings that are identifiers for authentication methods used in the authentication. This will allow the agencies to know if the user has used 1-factor or 2-factors when authenticating.            <br></p><table><thead><tr><th>Authentication Methods</th><th>Value</th></tr></thead><tbody><tr><td>1FA</td><td>[“pwd”]</td></tr><tr><td>2FA SMS OTP</td><td>[“pwd”,”sms”]</td></tr><tr><td>2FA HW Token</td><td>[“pwd”,”hwk”]</td></tr><tr><td>2FA Soft Token (Push)</td><td>[“pwd”,”swk”]</td></tr><tr><td>QR Code</td><td>[“pwd”,”swk”]</td></tr></tbody></table><p>                               <br></p></td></tr></tbody></table>

### Authentication Types

Singpass provides three authentication types, however, each authentication type is granted according to your company profile.

| Client Profile                                        | Descriptions                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">`QR Authentication`</mark>  | This method allow users to scan a QR code displayed on the Singpass login page using the Singpass Mobile App on for authentication. It provides a convenient and secure way to log in without needing to enter a username or password directly on the device.                                                               |
| <mark style="color:blue;">`1FA Authentication`</mark> | This method requires users to provide their Singpass ID and password when requested on the Singpass login page for authentication.                                                                                                                                                                                          |
| <mark style="color:blue;">`2FA Authentication`</mark> | 2FA adds an additional layer of security beyond just a Singpass ID and password. It typically involves combining two different types of authentication factors. After providing Singpass ID and password,  users can select Face Verification or enter a One-Time Password sent via SMS to complete the 2FA authentication. |

### Next steps

* Understand the [prerequisite](#discovery-endpoint) for integrating with Singpass.
* If you already have it, proceed to [setup your application](https://ndi-px.gitbook.io/singpassdevdocs/getting-started/understanding-the-basics/configure-singpass-application-on-sdp-in-progress) with Singpass.
