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 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. 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.

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`

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.
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:

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.

Expand for a Postman collection for testing

{
"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, phone number, email address, and national ID number.

To send the request:

Copy the authorization request from the bottom of OpenID Connect Debugger.
Add &login_hint={value} to the end of the URL.
Paste the full URL into your browser and press Enter.