OIDC Basics
- Home
- OIDC Basics
This page is for Authlete 3.0. For 2.x, refer to this page.
Introduction
This document is a tutorial to describe basic usage of Authlete APIs in order to implement OpenID Connect (OIDC) identity provider (IdP) server that supports the authorization code flow. In completing the tutorial, you will- Make requests simulating the requests which come from the authorization server to Authlete
- Set the issuer identifier in the Authlete Management Console, include additional claims in the authorization request to the Authlete authorize endpoint, and confirm that both the issuer and additional claims are included in the ID Token by decoding it.
Authorization Code Flow Components
Note In this tutorial, OIDC identity provider and relying party are described as authorization server and client respectively for convenience. In a typical Authlete implementation, the authorization server middleware would be responsible for passing requests to and handling responses from the Authlete API. In this tutorial, you will make these requests directly with the bash/zshcurlcommand. You may of course use an alternate HTTP client of your choice (PowerShell, Postman, etc.), but you’ll need to know how to adapt the instructions for yourself in this instance. flowchart LR subgraph EndUser [End User] userAgent[“User Agent (N/A)”] resourceOwner[“Resource Owner (N/A)”] end subgraph APIClient [API Client] client[“Client (N/A)”] end subgraph APIServer [API Server] authServer[“Authorization Server/IdP (curl)”] resourceServer[“Resource Server (curl)”] authAdmin[“Authlete Administrator”] end subgraph Authlete [Authlete] mgmtConsole[“Authlete Management Console”] authAPI[“Authlete API”] end resourceOwner —> userAgent userAgent — “Access to Client” —> client userAgent — “Authorization Request (User Authentication and Consent)” —> authServer client — “Token Request” —> authServer client — “API Request” —> resourceServer %% API Server interactions with Authlete authAdmin — “Service/Client Management” —> mgmtConsole mgmtConsole — “API Request” —> authAPI authServer — “API Request” —> authAPI resourceServer — “API Request” —> authAPI To understand how each piece fits together in this OAuth flow, we’ve provided a list of fully qualified domain names (FQDN) for each component. The FQDNs for the authorization server and the client are invented only for reference, and would of course be substituted for real ones in a real implementation.Component FQDN Authlete API US Cluster us.authlete.comAuthlete Management Console console.authlete.comAuthorization Server as.example.comClient client.example.orgResource Server N/A Note API endpoints are cluster specific. If using a service in another cluster, you’d substitute in the cluster’s two character ISO code for the complete domain name for that API endpoint (e.g. br, eu, jp). Environment setup
Note Settings in this section are the same as described in Authlete API Tutorial - OAuth 2.0 Basics. If you’ve already completed that tutorial, you can skip this section. Consult instructions “Sign-up to Authlete and Creating a Service“ for how to create an Authlete API service and register a client to the service. Take care to note your Service ID, Service Access Token, and Client Secret values. If you’ve already completed other Authlete tutorials, you can reuse your existing service. Otherwise use the following values to create your service, leaving all other fields as default:Field Value API Cluster 🇺🇸 US Service Name Demo AS Service Description Example authorization service You can use the following values to create your client, leaving all other fields as default: Field Value --- --- Client Name Demo OIDC Client Client Description Example client for OIDC tutorial Client Type CONFIDENTIAL 
Once your client is created, go to Client Settings > Endpoints > Global Settings. In the Redirect URIs section, click Add to enter and save the URI where the client will receive authorization responses. The following example properties are generated or specified when you create a client. These are values required when making requests as part of the codeflow that you will complete. Use the values you noted down in the environment setup section.Item Value --- --- Service ID Auto-generated e.g. 10738933707579 Service Access Token Auto-generated e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQClient ID Auto-generated e.g. 12898884596863 Client Secret Auto-generated e.g. -olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmgClient Type CONFIDENTIALRedirect URIs https://client.example.org/cb/example.comClient Authentication Method CLIENT_SECRET_BASICNow, let’s try the OIDC authorization code flow using this environment. Walk-through
We’ve provided the following sequence diagram to help you understand each of the steps involved in the code flow. You can identify where you are at in the walk-through using the numbers which correspond to specific steps in the diagram. sequenceDiagram autonumber participant RO as Resource Owner participant UA as User Agent participant C as Client participant AS as Authorization Server participant RS as Resource Server participant API as Authlete API RO ->> UA: Start UA ->> C: Make a request C —>> UA: Authorization request UA ->> AS: Forward the request AS ->> API: POST /auth/authorization API —>> AS: OK to proceed(including ticket) AS —>> UA: User authentication and consent page RO UA: Enter credentials UA ->> AS: Login and consent AS ->> API: POST /auth/authorization/issue(with ticket) API —>> AS: Authorization response content(including authorization code) AS —>> UA: Authorization response UA ->> C: Forward the response C ->> AS: Token request(with authorization code) AS ->> API: POST /auth/token API —>> AS: Token response content(including id token & access token) AS —>> C: Token responseAuthorization request from the client to the authorization server
We’ll use the following values as example parameters for the request (as specified previously).Item Value Description response_type codeA value stating OIDC authorization code flow (when scopecontainsopenid)redirect_uri https://client.example.org/cb/example.comOne of registered redirect URIs scope openidA value stating this request is OIDC authentication request nonce n-0S6_WzA2MjNonce value (See 3.1.2.1. Authentication Request - OpenID Connect Core 1.0) When the resource owner attempts to access a protected resource through the client (steps #1, #2) the client makes an OIDC authentication request (authorization request) to the authorization server via user agent (steps #3, #4). The authorization server receives the above data here shown as the HTTP GETquery string from the user agent. - Whether the value of the redirect URI
https://client.example.org/cb/example.commatches with one of URIs registered to the client - Whether values of other parameters such as
response_type,scopeare applicable for the client, i.e. permitted for the client to specify in its request After that, the authorization server would process the OIDC authorization code flow since the values ofscopeandresponse_typeareopenidandcoderespectively. However, in the Authlete architecture the authorization server is simply a proxy for the actual authorization logic contained in the Authlete API which is surfaced at the /auth/authorization endpoint. Once received, the Authlete API does the evaluation process on the authorization server’s behalf. You’ll now simulate the authorization server’s request to this API. Execute thecurlcommand as follows (message #5). Make sure to replaceService ID>,Service Access Token>\}andClient ID>` by your own values generated in the previous step.
-H ‘Content-Type: application/json’
-d ‘Client ID e.g. 12898884596863>`}&scope=openid&nonce=n-0S6_WzA2Mj” }’
-H ‘Authorization: Bearer Service Access Token e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>’
-H ‘Content-Type: application/json’
-d ‘Ticket e.g. bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU>`}”, “subject”: “testuser01” }’
-H ‘Authorization: Bearer Service Access Token e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>’
-H ‘Content-Type: application/json’
-d ‘Client ID e.g. 12898884596863>`}”, “clientSecret”: “Client Secret e.g. -olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmg>”, “parameters”: “grant_type=authorization_code&code=Code e.g. GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U>`}&redirect_uri=https://client.example.org/cb/example.com” }’
-H ‘Authorization: Bearer Service Access Token e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>’
-H ‘Content-Type: application/json’
-d ‘Client ID e.g. 12898884596863>`}&scope=openid&nonce=n-0S6_WzA2Mj” `}’
-H ‘Authorization: Bearer Service Access Token e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>’
-H ‘Content-Type: application/json’
-d ‘Ticket e.g. JjQ_Th1UvZyU5MsdKTLIfLv3VlKwEiYnnULmW6l_d9A>`}”, “subject”: “testuser01”, “claims”: "" }’
-H ‘Authorization: Bearer Service Access Token e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>`}’
-H ‘Content-Type: application/json’
-d ‘Client ID e.g. 12898884596863>”, “clientSecret”: “Client Secret e.g. -olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmg>`}”, “parameters”: “grant_type=authorization_code&code=Code e.g. ILePyGjraVgeU_fzaQRfd0gv10pzxgcpHY_vHT2dsPI>`}&redirect_uri=https://client.example.org/cb/example.com” `}’