# OIDC Manual Configuration
Manual OpenID Connect (OIDC) configuration lets you create and manage OIDC clients directly in Dashboard, giving you control over settings that [automatic configuration](https://developer.incode.com/docs/oidc-automatic-configuration) pre-defaults for you, including which scopes to request, the post-logout redirect URI, and whether user consent is required. With automatic configuration, Incode ties the client directly to a Flow or Workflow and only lets you set the redirect URI. With manual configuration, scoping depends on your authentication type: onboarding authentication remains tied to a specific Flow or Workflow, while face authentication does not.
Use this approach when you need more control over your OIDC client's configuration or require specific authentication methods or grant types.
Your OIDC client is configured with:
- An authorization code grant
- A client secret for authentication
The OIDC client supports the following authentication methods:
- `client_secret_basic`
- `client_secret_post`
- `client_secret_jwt`
- `private_key_jwt`
Follow the steps on this page to configure your OIDC client. Complete them in order.
***
## Create an OIDC Client
Create a new OIDC client in Dashboard by [generating a new authorization protocol](https://developer.incode.com/docs/configuration-authorization-tab#generate-new-authorization-protocol). While following those steps:
- Copy the **_Authorize URL_**, **_Client ID_**, and **_Client Secret_**. You need those values for the remaining steps on this page.
- In **_Redirect URIs_** and **_Post Logout Redirect URIs_**, enter `https://oidcdebugger.com/debug`.
- Select any of the following checkboxes under **_Client Authentication Methods:_**
- `client_secret_basic`
- `client_secret_post`
- `client_secret_jwt`
- `private_key_jwt`
***
## Configure and Send the Authorization Request
Use OpenID Connect Debugger to test your authorization request and debug the response.
1. Enter the following values in the debugger:
| Field | Value |
| ------------- | --------------------------------------------------------------- |
| Authorize URI | Your Authorize URL from Dashboard. |
| Redirect URI | `https://oidcdebugger.com/debug` |
| Client ID | Your Client ID from Dashboard. |
| Scope | `openid`. Add any other registered scopes, separated by spaces. |
| State | Populated automatically. |
| Nonce | Populated automatically. |
| Response Type | `code` |
| Use PKCE | Select if required by your client configuration. |
| Response Mode | `fragment` |
2. Click **Send Request**. You are redirected to the Incode Authorization Server. What happens next depends on your authentication type:
- **Face authentication**: Click **Sign In with Incode** and take a selfie. If the user is already enrolled in your organization, authentication succeeds. If not, the user is prompted to sign up. If your Dashboard configuration requires user consent, a consent page appears listing the requested scopes. The user must accept at least one scope to proceed. Consent is saved per scope, so the user is only prompted once per scope.
- **Onboarding**: Scan the QR code with a mobile phone and complete the onboarding process. If the session status is `PASSED`, an authorization code is issued. If the status is `FAILED`, authentication is denied.
3. After successful authentication, copy the authorization code from the response. You will use it in the next step.
***
## Exchange the Authorization Code for Tokens
Send a `POST` request to `{oidc-base-url}/oauth2/token`. Replace `{oidc-base-url}` with the first part of your Authorize URL from Dashboard, before `/oauth2/authorize`. For example, if your Authorize URL is `oidc-saas.incodesmile.com/oauth2/authorize`, send the request to `oidc-saas.incodesmile.com/oauth2/token`.
Include the following parameters in the request body, formatted as `x-www-form-urlencoded`:
| Parameter | Description |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `grant_type` | Required. Must be `authorization_code`. |
| `client_id` | Required. Your Client ID from Dashboard. |
| `client_secret` | Required. Your Client Secret from Dashboard. |
| `redirect_uri` | Required. Must match the Redirect URI registered in Dashboard: `https://oidcdebugger.com/debug`. |
| `code` | Required. The authorization code from the previous step. |
The example above uses the `client_secret_post` authentication method. The parameters you send must match the authentication method configured for your OIDC client in Dashboard.
Authorization codes expire after five minutes. After expiration, the user must complete the authorization flow again. Sessions last one hour. During that time, you can retrieve multiple authorization codes, but only the most recent one is valid.
***
## Retrieve User Information
Send a `GET` request to `{oidc-base-url}/userinfo` . Replace `{oidc-base-url}` with the first part of your Authorize URL from Dashboard, before `/oauth2/authorize`. For example, if your Authorize URL is `oidc-saas.incodesmile.com/oauth2/authorize`, send the request to `oidc-saas.incodesmile.com/userinfo`.
Include the access token from the previous step in the Authorization header:
```http
GET {oidc-base-url}/userinfo
Authorization: Bearer {access_token}
```
Use the Postman desktop app for this request, not the web app. You must also configure the Postman Interceptor before sending.
```json
{
"info": {
"_postman_id": "fae0fbcd-5c8f-43e7-8cb4-e08804834f5e",
"name": "Authorization-Server Stage",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "9749190"
},
"item": [
{
"name": "well-known",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/.well-known/openid-configuration",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
".well-known",
"openid-configuration"
]
}
},
"response": []
},
{
"name": "jwks",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/.well-known/openid-configuration",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
".well-known",
"openid-configuration"
]
}
},
"response": []
},
{
"name": "/oauth2/introspect",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/oauth2/introspect",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"oauth2",
"introspect"
]
}
},
"response": []
},
{
"name": "authorization",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/oauth2/authorize?client_id=superapp886&scope=openid&state=soa9pjyqdm&redirect_uri=https://jsonlint.com/&response_type=code",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"oauth2",
"authorize"
],
"query": [
{
"key": "client_id",
"value": "superapp886"
},
{
"key": "scope",
"value": "openid"
},
{
"key": "state",
"value": "soa9pjyqdm"
},
{
"key": "redirect_uri",
"value": "https://jsonlint.com/"
},
{
"key": "response_type",
"value": "code"
}
]
}
},
"response": []
},
{
"name": "token client_secret_post auth method",
"request": {
"method": "POST",
"header": [
{
"key": "Cookie",
"value": "Cookie_1=value; XSRF-TOKEN=1e7a9269-bf7b-407d-b3a5-5791d0c7a405",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "grant_type",
"value": "authorization_code",
"type": "text"
},
{
"key": "client_id",
"value": "76f9d8f9c4864fa69c68e617e75d435c",
"type": "text"
},
{
"key": "client_secret",
"value": "$LT0AxiQj5W6AqwU#rl_",
"type": "text"
},
{
"key": "redirect_uri",
"value": "https://oidcdebugger.com/debug",
"type": "text"
},
{
"key": "code",
"value": "MHRSot7hw8GSlSvyHAQrl7Fd6bqXXsL4QiluKp6y00RXKGFt5aVG3LEfXfUxYIlADgkppvIxwOZHDToqDzA3Q0bPtbH_bfRI26h_ENfTq7PEapHDBFF0JWpNaBhpS4u1",
"type": "text"
}
]
},
"url": {
"raw": "https://oidc-stage-us.stage.incodetest.com/oauth2/token",
"protocol": "https",
"host": [
"oidc-stage-us",
"stage",
"incodetest",
"com"
],
"path": [
"oauth2",
"token"
]
}
},
"response": []
},
{
"name": "token client_secret_post auth method PKCE",
"request": {
"method": "POST",
"header": [
{
"key": "Cookie",
"value": "Cookie_1=value; XSRF-TOKEN=1e7a9269-bf7b-407d-b3a5-5791d0c7a405",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "grant_type",
"value": "authorization_code",
"type": "text"
},
{
"key": "client_id",
"value": "09d6202eb7454348ab4c64d82d61ca5a",
"type": "text"
},
{
"key": "client_secret",
"value": "(V6In#Cm^c@tbB0)bDM5",
"type": "text"
},
{
"key": "redirect_uri",
"value": "https://oidcdebugger.com/debug",
"type": "text"
},
{
"key": "code",
"value": "JUHf7ffkieiI81Yolu47Fknk1LAg4C8a4akNYPzHbODUlXI7HbPPI7QKawKwf2kigL8jxPFWAsUc5oO5P-BJ6CfJHxiDhmPh5klXVj5ukdehijEQPrh98fQ9BrbqpiQ4",
"type": "text"
}
]
},
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/oauth2/token",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"oauth2",
"token"
]
}
},
"response": []
},
{
"name": "token jwt",
"request": {
"method": "POST",
"header": [
{
"key": "Cookie",
"value": "Cookie_1=value; XSRF-TOKEN=1e7a9269-bf7b-407d-b3a5-5791d0c7a405",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "redirect_uri",
"value": "https://oidcdebugger.com/debug",
"type": "text"
},
{
"key": "code",
"value": "TGwBAuaexqWZvkVjO0QDGNUC9i7fHyNlcuPw68rSRDVm6VQc-TslA_IB39OV2PGoT8FRrnu20odmdP6HZh_88RJdt8Sx7GbDvZkyk6YUtGAMjLjeKe0t3aV0n8vzGKLN",
"type": "text"
},
{
"key": "client_assertion_type",
"value": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"type": "text"
},
{
"key": "client_assertion",
"value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwOWQ2MjAyZWI3NDU0MzQ4YWI0YzY0ZDgyZDYxY2E1YSIsInN1YiI6IjA5ZDYyMDJlYjc0NTQzNDhhYjRjNjRkODJkNjFjYTVhIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAxMi9vYXV0aDIvdG9rZW4iLCJqdGkiOiI1NjQ1MjU0MjIyNDIiLCJleHAiOiIxNjg4ODIwOTE2In0.SZ9eJ0uFOGTtAagLKVl9nax3uYEp62PBVdH3Wo9ti1A",
"type": "text"
},
{
"key": "client_id",
"value": "09d6202eb7454348ab4c64d82d61ca5a",
"type": "text"
}
]
},
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/oauth2/token",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"oauth2",
"token"
]
}
},
"response": []
},
{
"name": "token client_secret_basic auth method",
"request": {
"method": "POST",
"header": [
{
"key": "Cookie",
"value": "Cookie_1=value; XSRF-TOKEN=1e7a9269-bf7b-407d-b3a5-5791d0c7a405",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "grant_type",
"value": "authorization_code",
"type": "text"
},
{
"key": "client_id",
"value": "09d6202eb7454348ab4c64d82d61ca5a",
"type": "text"
},
{
"key": "client_secret",
"value": "(V6In#Cm^c@tbB0)bDM5",
"type": "text"
},
{
"key": "redirect_uri",
"value": "https://oidcdebugger.com/debug",
"type": "text"
},
{
"key": "code",
"value": "JUHf7ffkieiI81Yolu47Fknk1LAg4C8a4akNYPzHbODUlXI7HbPPI7QKawKwf2kigL8jxPFWAsUc5oO5P-BJ6CfJHxiDhmPh5klXVj5ukdehijEQPrh98fQ9BrbqpiQ4",
"type": "text"
}
]
},
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/oauth2/token",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"oauth2",
"token"
]
}
},
"response": []
},
{
"name": "user info",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer eyJraWQiOiIwOWRiMzI2My0zYWE3LTQwZTQtYTg1NS1lMTIyNmY5NDZlMTgiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI2NTQ4Y2RhMDE3MjkwZjI5Y2ZlYjExYjIiLCJhdWQiOiI3NmY5ZDhmOWM0ODY0ZmE2OWM2OGU2MTdlNzVkNDM1YyIsIm5iZiI6MTY5OTI3MDkxMywic2NvcGUiOlsib3BlbmlkIiwicHJvZmlsZSIsInNlbGZpZSJdLCJpc3MiOiJodHRwczovL29pZGMtc3RhZ2UtdXMuc3RhZ2UuaW5jb2RldGVzdC5jb20iLCJleHAiOjE2OTkyNzEyMTMsImlhdCI6MTY5OTI3MDkxM30.YInfHrtorh37oij2KIxWMb8cEtTyG9SsaGDsYBWSCEkP74sCJ_nxoqmTtmxL6KryRITZNiRnrScfVCTqacxybZF5bXe7E6kVr6v2Vv-PaPWoueR4wHOiBRfOhecRycZlDzfgf4nWpLfbzV9p0_k-Kier6m1X2T5wQuavYErwQcErQP2YfO_37KXs1JKGTzl2-g5xWwNPwqXVcUuQqqpAM09PVu7ffqngfztLiSXDbg5Hf8XkEhc8hdrEtmuuaoFNJ9jCXjUUxSbHi2skAvCj8aIFZcj64TNL8po6XnNNdcE4b2MLARhQUH8hQl18xk0OLOzyJAjYRSWyiKOyF9KPZQ",
"type": "text"
},
{
"key": "Cookie",
"value": "Cookie_1=value; JSESSIONID=C94F8D8057EC9CAA36365D2B2784C98D",
"type": "text"
}
],
"url": {
"raw": "https://oidc-stage-us.stage.incodetest.com/userinfo",
"protocol": "https",
"host": [
"oidc-stage-us",
"stage",
"incodetest",
"com"
],
"path": [
"userinfo"
],
"query": [
{
"key": "grant_type",
"value": "authorization_code",
"disabled": true
},
{
"key": "client_id",
"value": "superapp886",
"disabled": true
},
{
"key": "client_secret",
"value": "secret",
"disabled": true
}
]
}
},
"response": []
},
{
"name": "logout",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "id_token_hint",
"value": "eyJraWQiOiI0YmJiNTZiMi1lMTM4LTRmNjctOGFhZi0wNjg5MTU5OGE5YjEiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI2NDkwMzMxMzBiNjVmMmFjM2ZhMDc2MmMiLCJhdXRoX3Bob3RvX3F1YWxpdHlfdmFsdWUiOjEwMi40OTksImlzcyI6Imh0dHA6Ly9pbmNvZGUtZGV2ZWxvcC1vaWRjLTExNjMwMDUzNjEudXMtd2VzdC0yLmVsYi5hbWF6b25hd3MuY29tIiwiYXV0aF9vdmVyYWxsX3Njb3JlIjowLjc0MjE0MSwibm9uY2UiOiI1c2R0ejUwc2F3Iiwic2lkIjoiaEtpT0lPdGxNRk9fcHdoZVRPTTBvQ3dySzFaODJHZ2pYN0NuSVVOYjg3QSIsImF1ZCI6ImEwODY5ZTBiYjIzMDRjZTU4MmE3N2RiMTFkZGM3NWRlIiwiYXV0aF9vdmVyYWxsX3N0YXR1cyI6IlBBU1MiLCJhenAiOiJhMDg2OWUwYmIyMzA0Y2U1ODJhNzdkYjExZGRjNzVkZSIsImF1dGhfdGltZSI6MTY4ODYzNTEyOCwiaW50ZXJ2aWV3X2lkIjoiNjQ5MDI1ZTUwYjY1ZjJhYzNmOWU4ZmI1IiwiZXhwIjoxNjg4NjM2OTQwLCJpYXQiOjE2ODg2MzUxNDB9.XskcaGx1CRTpAE6A4jwSUV180UwCDPiOCStU1Y7NPlc_6-yJeoU6Wc1APmR_B2IXrksL3mEVFsymppk2pIaA32SLK0X-JMoBZlDRL-z4GSUoZhaTcvvBGAbQnCBR5MSHSg9wrG0muCqH-hqx1L9H0MyNMNtGhQk3BSpi47rw1yceUlO308pr_I5PQcMsJ7ho3SOgUV4GnAlkR9h2K-zGZiojdJok9J0f_R_umjAOzlY0kywPZ8na9miGaPLCNLFJA1dGOncbLGb8OgUVhYoij1K73UvPezuTCeRqZsoh6ksaxI_I-EiTiikpxX5694ojXLwBzBOWcOgi4TJV82jD2w",
"type": "text"
},
{
"key": "client_id",
"value": "a0869e0bb2304ce582a77db11ddc75de",
"type": "text"
},
{
"key": "post_logout_redirect_uri",
"value": "https://oidcdebugger.com/debug",
"type": "text"
}
]
},
"url": {
"raw": "https://incode-develop-oidc-1163005361.us-west-2.elb.amazonaws.com/connect/logout",
"protocol": "https",
"host": [
"incode-develop-oidc-1163005361",
"us-west-2",
"elb",
"amazonaws",
"com"
],
"path": [
"connect",
"logout"
]
}
},
"response": []
}
]
}
```
### Test with a Specific User
To test authentication for a specific user, add `login_hint` as a parameter to your `/authorize` request. The value depends on how your OIDC client is configured in Dashboard. Accepted value types are: [UUID](https://developer.incode.com/docs/glossary#customer-uuid), phone number, email address, and national ID number.
To send the request:
1. Copy the authorization request from the bottom of OpenID Connect Debugger.
2. Add `&login_hint={value}` to the end of the URL.
3. Paste the full URL into your browser and press Enter.