OAuth / OpenID Connect Server

A) Authorization Grant: The application first needs to decide which permissions it is requesting, then sends the user to a browser to get their permission. To initiate this authorization flow, form a URL as below and redirect the end user's browser to the URL:

GET <authorization-endpoint>? response_type=code &client_id=<client_id> &redirect_uri=<callback_url> &scope=openid&state=<security_token>

• If the user allows access to your app, their browser will be redirected to the supplied redirect url and request will include code and state parameters in the query string.
• For example, the user can be redirected back to URL such as
  https://callback-url/?code=<authorization-code>&state=<security_token>
• The code is Authorization code which can be exchanged for Access token. It is generated by the authorization server and is relatively short lived. The state is the same security token that the application initially set in the request.

B) Token Request:

• If the end user granted your app access and you receive an Authorization Code, you can exchange the Authorization Code for an Access Token by making a POST request to the token endpoint.
• The following is an example for POST request: POST <token-endpoint> Request Header: Content-Type: application/x-www-form-urlencoded Request Body: grant_type=authorization_code &code=<authorization_code> &client_id={clientId} &client_secret={clientSecret} &redirect_uri=<redirect_uri>
• Here, is the description for each request parameter:

  Field	Description
  <token-endpoint>	Token endpoint that you get from the Step 1 above.
  grant_type	The type of grant you are providing. This tells that the application is using authorization code grant type.
  code	The authorization code received in previous step, included here.
  redirect_uri	The same uri that was provided earlier in the authorization request.
  client_id	The client ID provided by the OpenID Connect(OIDC) provider.
  client_secret	The client secret provided by the OpenID Connect(OIDC) provider.

• At the token endpoint all the parameters in the request will be verified ensuring that the code hasn't expired and the client id and secret matches. If the Request is successful, it will generate an id token & access token and return it in the response: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4Y W1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0 wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V 8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPe B2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E 2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfub EEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" "access_token": "SlAV32hkKG", "token_type": "Bearer", "expires_in": 3600, }
• Here, is the description for each parameter received in the response.

  Field	Description
  id_token	The ID Token is a security token that contains Claims about the authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims.
  access_token	Access token for the Userinfo endpoint.
  token_type	OAuth 2.0 token type value. The value must be Bearer.
  expires_in	The expiry time for the access token.
  client_secret	The client secret provided by the OpenID Connect(OIDC) provider.

• If the request fails the response will have a status of 404 Bad Request and will have the following contents: "error" : "invalid_request", "error_description" : "A more detailed description of the error intended for the developer of your app."

C) Resource Request:

• If the token request is successful, you will get access_token in the response which can be used to access the protected resources via the API.
• Userinfo Request: The following is a non-formative example of Userinfo Request: GET <userinfo-endpoint> Request Header Authorization: Bearer <access_token>
• Here, is the description for each parameter received in the response.

  Field	Description
  <userinfo-endpoint>	Userinfo endpoint that you get from the Step 1 above.
  access_token	Access token for the Userinfo endpoint.

• The resource server validate and verify the access token and checks if it has not expired. If the resource request is valid the resource server returns the claims which are represented by a JSON object that contains a collection of name and value pairs for the Claims.
• Successful Userinfo Response: The UserInfo Claims MUST be returned as the members of a JSON object.
• Below is the example: { "sub" : "abxc", "email" : "xyz@example.com", "email_verified" : true, "name" : "xyz pqr", "given_name" : "xyz", "family_name" : "pqr", "phone_number" : "+359 (99) 100200305", "profile" : "https://test.com/xyz", "https://c2id.com/groups" : [ "audit", "admin" ] }

A) Authorization Request: The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To initiate this implicit flow, form a URL as below and redirect the end user's browser to the URL:

GET <authorization-endpoint>? response_type=<token> &client_id= <client_id_goes_here> &redirect_uri= <callback_url> &scope= <openid> &state= <security_token>

• If the user allows access to your app, their browser will be redirected to the supplied redirect url and request will include token and state parameters in the query string.
• For example, the user can be redirected back to callback URL such as
  https://callback-url? #id_token=<id_token> &token_type=Bearer &expires_in=3600 &state=<security_code>
• Note the two major differences between this and the Authorization Code flow: the access token & id_token is returned instead of the authorization code in the response.
• The client can then use the access_token to access protected resources from Resource server.
• Here, is the description for each parameter received in the response.

  Field	Description
  id_token	The ID Token is a security token that contains Claims about the authentication of an End-User by an Authorization Server when using a Client, and potentially other requested claims.
  access_token	access token for the Userinfo endpoint.
  token_type	OAuth 2.0 token type value. The value must be Bearer.
  expires_in	The expiry time for the access token.
  scope	One or more space seperated strings which indicates the permission your application requesting.

B) Resource Request:

• The UserInfo Endpoint claims about the authenticated End-User. The returned Claims are represented by a JSON object that contains a collection of name and value pairs for the claims.
• The following is a non-formative example of Userinfo Request: GET <userinfo-endpoint> Request Header Authorization: Bearer <access_token>
  

  Field	Description
  <userinfo-endpoint>	Userinfo endpoint that you get from the Step 1 above.
  access_token	Access token for the Userinfo endpoint.
  Successful Userinfo Response	The UserInfo Claims MUST be returned as the members of a JSON object.

• Below is the example: { "sub" : "abxc", "email" : "xyz@example.com", "email_verified" : true, "name" : "xyz pqr", "given_name" : "xyz", "family_name" : "pqr", "phone_number" : "+359 (99) 100200305", "profile" : "https://test.com/xyz", "https://c2id.com/groups" : [ "audit", "admin" ] }

The resource owner password (or "password") grant type is mostly used in cases where the app is highly trusted. In this configuration, the user provides their resource server credentials (username/password) to the client app, which sends them in an access token request.

A) Token Request: The Password grant involves only one step: the application presents a traditional username and password login form to collect the user’s credentials and makes a POST request to the server to exchange the password for an access token. The POST request that the application makes looks like the example below:

POST <token-endpoint> Request Header Content-type: application/x-www-form-urlencoded Request Body grant_type=password &username=exampleuser &password=12345678 &client_id=xxxxxxxxxx

• The POST parameters in this request are explained below:

  Field	Description
  <token-endpoint>	Token endpoint that you get from the Step 1 above
  grant_type	This tells the server we’re using the Password grant type
  username	The user’s username that they entered in the application
  password	The user’s password that they entered in the application
  client_id	The public identifier of the application that the developer obtained during registration

• The server replies with an access token in the same format as the other grant types.
• For example, the user can be redirected back to callback URL such as: https://callback-url? #access_token=<access_token> &token_type=Bearer &expires_in=3600 &id_token=<id_token>
• The client can then use the access_token to access protected resources from Resource server.
• Here, is the description for each parameter received in the response:

  Field	Description
  access_token	access token for the Userinfo endpoint.
  token_type	OAuth 2.0 token type value. The value must be Bearer.
  expires_in	The expiry time for the access token.
  id_token	The ID Token is a security token that contains Claims about the authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims

B) Resource Request:

• The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. The returned Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.
• Userinfo Request: The following is a non-formative example of Userinfo Request: GET <userinfo-endpoint> Request Header Authorization: Bearer <access_token>
• Here, is the description for each parameter received in the response.

  Field	Description
  <userinfo-endpoint>	Userinfo endpoint that you get from the Step 1 above.
  access_token	access token for the Userinfo endpoint.
  Successful Userinfo Response	The UserInfo Claims MUST be returned as the members of a JSON object.

• Below is the example: { "sub" : "abxc", "email" : "xyz@example.com", "email_verified" : true, "name" : "xyz pqr", "given_name" : "xyz", "family_name" : "pqr", "phone_number" : "+359 (99) 100200305", "profile" : "https://test.com/xyz", "https://c2id.com/groups" : [ "audit", "admin" ] }

Client Credentials grant can be used for machine to machine authentication. In this grant a specific user is not authorized but rather the credentials are verified and a generic access_token is returned.

A) Token Request: To receive an id token, the client POSTs an API call with the values for Client ID and Client secret obtained from a registered developer app as follow:

POST <token-endpoint> Request Header Content-Type: application/x-www-form-urlencoded Request Body grant_type=client_credentials& client_id={client_id}& client_secret={clientSecret}

• Request Parameters: The POST request parameters are explained below:

  Field	Description
  grant_type	This tells the server we’re using the client credentials grant type.
  client_id	The public identifier of the application that the developer obtained during registration.
  client_secret	The client secret provided by the OIDC provider.
  redirect_uri	Callback Url to which user will be redirected once they allow or disallow the access to your app.
  scope	One or more space separated strings which indicates the permission your application requesting.

• If the credentials are valid, the application will receives an access token for a client.
• Sample Response:
{ "access_token": , "expires_in": 600, "token_type": "Bearer" }

• Here, is the description for each parameter received in the response:
  

  Field	Description
  access_token	access token for the Userinfo endpoint.
  token_type	OAuth 2.0 token type value. The value must be Bearer.

A Refresh Token allows the application to issue a new Access Token or ID Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked.

A)Refresh Token Request: The response of token request should contain access token ans refresh token.

• Use a Refresh Token: To exchange the Refresh Token you received for a new Id Token, make a POST request to the token endpoint, using grant_type=refresh_token as follows: POST <token-endpoint> Request Header Content-Type: application/x-www-form-urlencoded Request Body grant_type=refresh_token& client_id={client_id}& client_secret={client_secret}& refresh_token={refresh_token}
• Here, is the description for each request parameter:

  Field	Description
  <token-endpoint>	Token endpoint that you get from the Step 1 above.
  grant_type	This tells the server we’re using the refresh token grant type.
  client_id	The public identifier of the application that the developer obtained during registration.
  client_secret	The client secret provided by the OAuth provider.
  refresh_token	The refresh token to use.

• The response will include a new ID Token and Access Token , its type, its lifetime (in seconds), and the granted scopes. Response will contain parameters as follows: { "access_token": "eyJ...MoQ", "expires_in": 86400, "scope": {scope}, "id_token": "eyJ...0NE", "token_type": "Bearer" }

B) Revoke a Refresh Token: Since Refresh Tokens never expire, it is essential to be able to revoke them in case they get compromised.

• To revoke a Refresh Token, you can send a POST request to token endpoint as follows: POST <revoke-endpoint> Request Header Content-Type: application/x-www-form-urlencoded Request Body client_id={client_id}& client_secret={client_secret}& refresh_token={refresh_token}
• Here, is the description for each request parameter:

  Field	Description
  <revoke-endpoint>	Revoke endpoint that you get from the Step 1 above.
  client_id	The public identifier of the application that the developer obtained during registration.
  client_secret	The client secret provided by the OAuth provider.
  refresh_token	The refresh token to use.