Authorization Code Grant

The Authorization Code Grant flow authorizes your application for a RICOH Cloud API service. You can use this authorization flow for some, but not all, services. See Authorization Type to understand the difference of supported authorization types and find the right one for the service you wish to use. In order to acquire a token with Authorization Code Grant, it is necessary to acquire client ID and client secret and register at least one redirection URI at Management Console.

Contents

• API Flow
• Endpoints
• How to Obtain an Access Token and User Information
  • How to Obtain Code
  • How to Obtain an Access Token
  • How to Obtain User Information
• ID Token
  • Headers and Payload
  • ID Token Validation
• How to Manage Token Expiration
• Samples
• See Also

Pre-Registration

In order to obtain an access token, it is necessary to issue client ID and client secret and link your client to services you wish to use at Management Console.

If you wish to use services which authorized with Authorization Code Grant, You must register redirection URIs. Multiple redirection URIs can be registered, up to 16 can be specified. The redirection URI has the following restrictions:

• Protocols you can specify are http or https only.
• The redirection endpoint URI MUST be an absolute URI (RFC3986 Section 4.3).
• application/x-www-form-urlencoded formatted query component (RFC3986 Section 3.4).
• The redirection URI MUST NOT include a fragment component.

Note: The characters that you can use to compose redirection URI are reserved characters, non-reserved characters,% encoding defined by RFC 3986.

API Flow

In this section, we will explain the flow until your application obtains the access token and ID token and obtains the end user information from the authorization server.

1. The end user accesses your application and presses the login button.
2. Your application redirects the request to the authorization server.
3. The user agent sends an authentication request to the authorization server.
4. The authorization server displays the login / registration page with RICOH Account.
5. The end user enters his/her ID and password. If the end user has not registered for RICOH Account, register at this moment.
6. The authorization server verifies the ID and password.
7. The authorization server redirects the user agent to your application (the redirection URI).
8. The application receives an Authorization Code as the query parameter of the redirection URI.
9. The application sends a token request to the authorization server with the Authorization Code and its credentials (client ID and client secret).
10. The authorization server verifies the authorization code.
11. The authorization server verifies the client ID and client secret.
12. The authorization server returns an access token and an ID token.
13. The application sends an userinfo request to the authorization server with the access token.
14. The authorization server returns the user information.
15. The application sends a request with the access token to RICOH Cloud API services.

Endpoints

Authorization code Grant provides the following endpoints:

Obtain an Access Token and User Information

In this section, we will explain how to request the following three requests and the contents of success full response and error response:

• Authentication Request for obtaining authorization code.
• Token Request for obtaining access token and ID token.
• Userinfo Request for obtaining user information.

Obtain an Authorization Code (Authentication Request)

As described in API Flow, when sending a GET request with the required parameters toward the authorization endpoint, the authorization server displays the end user authentication page. If the end user is successfully authenticated, the authorization server issues an authorization code and redirects the user agent to the specified URI. The authorization code is given as a query parameter of the redirection URI.

The following is an example of an authentication request that requests an authorization code. You must add required parameters to authorization endpoint URI as query parameters. It is necessary to specify client_id, redirect_uri, state, nonce and scope as parameters. In the example below, the Peer-to-Peer Communication API, openid and email are specified as scope:

GET /v1/authorization?
 scope=openid%20email%20%20turn.api.ricoh%2Fv1%2Fturn&
 response_type=code&
 client_id=53f28645f91ee076ed69aae337b796&
 redirect_uri=https%3A%2F%2Fexample.org%2Fcb&
 state=357ad73e8cb5065d362dc5a311b93b&
 nonce=SSdGoJdPxQdH6Uck+lNwf07Ks5ZY38wl2O5RoVvT0rCGYOb HTTP/1.1
 
Host: auth.api.ricoh
Content-Type: application/x-www-form-urlencoded

This endpoint supports the following parameters:

Here is scope value that specifies user information. For details about the each claim (sub, email, email_verified, name) please refer to ID Token.

Note: You must specify openid and at least one service code in the scope parameter.

Good scopes:

• openid turn.api.ricoh/v1/turn
• openid email turn.api.ricoh/v1/turn
• openid email profile turn.api.ricoh/v1/turn

Bad scopes:

• turn.api.ricoh/v1/turn
• email turn.api.ricoh/v1/turn
• openid

Successful Response

If an end user authentication is successful, the authorization server redirects the user agent to the redirection URI specified in the authentication request. At this time, the authorization server will give two parameters, state and code, as query parameters. The following is an example of response. Here, https: //example.org/cb is the same uri that was specified as the redirection URI in the authentication request.

HTTP/1.1 302 Found
  Location: https://example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

The meanings of the parameters included in the query parameter are as follows:

To prevent cross-site request forgery attack, your application must confirm that the state value in the authentication response matches the value specified in the authentication request. For details, please refer RFC6819.

Error Response

If the authentication request fails, the authorization server redirects the user agent to the URI specified in the authentication request giving the information on the error as query parameters. However, if the authorization server fails to validate of the value set in the redirect_uri parameter in the authentication request, it returns an error page.

HTTP/1.1 302 Found
  Location: http://example.com/cb?error=invalid_request&state=357ad73e8cb5065d362dc5a311b93b

The parameters included in the query parameter of the error response are as follows:

You might encounter the following errors:

Note: The HTTP Status Code listed in the table above is the value when returning the error page. If redirect response is returned, the value of status code is 302.

Obtain an Access Token and ID Token (Token Request)

You can obtain an access token and an ID token by making a POST request to the token endpoint with required parameters. Make a request with your application’s credentials and the authorization code you got from the authentication response. The following example is a token request to obtain an access token.

POST /token HTTP/1.1
Host: auth.api.ricoh
Authorization: Basic YTk0YWIwMmQtMTZlZC00YWM4LTgxY2ItNjBmODA1YTVlZTUwOkZqVi81d2JONDlTdWVlbkhuc3BqZHBtUUtNUlpVNU9LZXoydjdrVWs=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2Fexample.org%2Fcb

This endpoint supports the following headers:

This endpoint supports the following parameters:

Note: You can use one authorization code only once. Once you obtain the access token, if you want to get the access token again, you need to redo the authentication request and reacquire the authorization code.

Successful Response

The authorization server returns a JSON-formatted response when your request succeeds. If the example request above succeeds, the server returns a response like this:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store
Pragma: no-cache

 {
   "access_token": "yJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vYXV0aC5kZXYuYXBpLnJpY29oL3YxL2Rpc2NvdmVyeS9rZXlzIiwia2lkIjoiMmIyZTgyMTA2NzkxZGM4ZmFkNzgxNWQ3ZmI1NDRhNjJmNzJjMTZmYSJ9.eyJpc3MiOiJodHRwczovL2F1dGguZGV2LmFwaS5yaWNvaC8iLCJhdWQiOiJodHRwczovL2lwcy5kZXYuYXBpLnJpY29oLyIsImlhdCI6MTQ5MDg1Mjc0MSwiZXhwIjoxNDkwODU2MzQxLCJjbGllbnRfaWQiOiI4ODQwMWU1MS05MzliLTQ3NzktYjdmNy03YzlmNGIzZjkyYzAiLCJzY29wZSI6Imh0dHBzOi8vaXBzLmRldi5hcGkucmljb2gvdjEiLCJyaWNvaF9tc3MiOnsibWVkaWEiOnsicXVvdGEiOjEwLCJ0aHJvdHRsZSI6eyJ2YWx1ZSI6MCwid2luZG93IjowfX19fQ.jVq_c_cTzgsLipkJKBjAHzm8KDehW4r-FA1Yg0EQRmqWmBDlEKtpRpDHZeF6ZSQfNH2OlrBWFBiVDV9Th091QFE-YrZETZ1IE1koAO14oj4kf8TCmhiG_CtJagvctvloW1wAdgMB1_Eubz9a8oimcODqL7_uTmA5jKFx3ez9uoqQrEKZ51g665jSI6NlyeLtj4LrxpI9-jZ4zTx1yqqjQx0doYQjBPhOB06Z5bdiVyhJDRpE8ksRCC3kDPS2nsvDAal28sMgyeP8sPvfKvp5sa2UsH78WJmTzeZWcJfX2C2ba3xwRMB5LaaVrQZlhj9xjum0MfDpIS1hJI6p5CHZ8w",
   "token_type": "Bearer",
   "expires_in": 300,
   "scope": "openid email turn.api.ricoh/v1/turn",
   "api_key":"be4fc9db0dfd4e35b2faae2e8d4df52b",
   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImE4YjliYmVmYTFmZDQwZmU3NTQ4In0.eyJpc3MiOiJodHRwczovL2F1dGguZGV2LmFwaS5yaWNvaC92MSIsInN1YiI6ImI3Mjg1MzI5YWFlYzQ5ZTVkNDJhZTY1ZTdiYWY3YWFkNTkyODNiMTMxY2ZmM2U3NzhlNDE3NTgyZTY2YzNkNjQiLCJhdWQiOiJmZTI2MTBjYi03OWQzLTRiMTUtYjM0ZC1hOTI0ZDI5Njc3MzkiLCJleHAiOjE1MDc2OTMzMDMsImlhdCI6MTUwNzY5MzAwMywiYXV0aF90aW1lIjoxNTA3Njg1NzgxLCJub25jZSI6ImR1bW15X2FwcF9ub25jZSJ9.MZ0yFFuvWFR_3JxfqT2nZlnSg09qRtzmhhQDZMfDoLMv1g7C7qYDgRU7Z_a6OeQsRWbfKTa-ZMz18JAw8lYTEFOUg--BL1ukD6dMnZWsBaw1alJbwKXNZWY7gZXSJd9WBd5XZCp4xDrfXW_vbAH1PMu1PCO3U7DCfMyktYmcaPs2eHSjrkNwiQNAAq75nWXcDNoYtkZzK1av-LSlm23nufsvI77uKWsTw9pDRViVyIXLefUBBz-ygGVzfBOYzB-WftTwo2nk0hnw21bWmpcsGegdWhwYTxGXqhBGI_qZs51Qk4xP4LUgrSd3MNo9OQVjoNss1VEqT99W4kU7jWdyHQ"
  }

This endpoint’s responses include the following fields:

Note: You must validate the ID token. For details, refer to ID Token.

Error Response

The authorization server also returns a JSON-formatted response when your request fails. Here is an example of error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."
}

Error responses include the following fields:

You might encounter the following errors:

Obtain User Information (Userinfo Request)

You can get user information by sending a GET request to the userinfo endpoint with the access token. Set an access token according to the Bearer scheme in the authorization header of the request.

GET /userinfo HTTP/1.1
Host: auth.api.ricoh
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vYXV0aC5kZXYuYXBpLnJpY29oL3YxL2Rpc2NvdmVyeS9rZXlzIiwia2lkIjoiMmIyZTgyMTA2NzkxZGM4ZmFkNzgxNWQ3ZmI1NDRhNjJmNzJjMTZmYSJ9.eyJpc3MiOiJodHRwczovL2F1dGguZGV2LmFwaS5yaWNvaC8iLCJhdWQiOiJodHRwczovL2lwcy5kZXYuYXBpLnJpY29oLyIsImlhdCI6MTQ5MDg1Mjc0MSwiZXhwIjoxNDkwODU2MzQxLCJjbGllbnRfaWQiOiI4ODQwMWU1MS05MzliLTQ3NzktYjdmNy03YzlmNGIzZjkyYzAiLCJzY29wZSI6Imh0dHBzOi8vaXBzLmRldi5hcGkucmljb2gvdjEiLCJyaWNvaF9tc3MiOnsibWVkaWEiOnsicXVvdGEiOjEwLCJ0aHJvdHRsZSI6eyJ2YWx1ZSI6MCwid2luZG93IjowfX19fQ.jVq_c_cTzgsLipkJKBjAHzm8KDehW4r-FA1Yg0EQRmqWmBDlEKtpRpDHZeF6ZSQfNH2OlrBWFBiVDV9Th091QFE-YrZETZ1IE1koAO14oj4kf8TCmhiG_CtJagvctvloW1wAdgMB1_Eubz9a8oimcODqL7_uTmA5jKFx3ez9uoqQrEKZ51g665jSI6NlyeLtj4LrxpI9-jZ4zTx1yqqjQx0doYQjBPhOB06Z5bdiVyhJDRpE8ksRCC3kDPS2nsvDAal28sMgyeP8sPvfKvp5sa2UsH78WJmTzeZWcJfX2C2ba3xwRMB5LaaVrQZlhj9xjum0MfDpIS1hJI6p5CHZ8w
Content-Type: application/x-www-form-urlencoded

Successful Response

The authorization server returns a JSON-formatted response which includes user information. The information contained in the response depends on the scope value specified in the authentication request.

HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
   "sub": "6bef6a24b1a743ae72496efa1a99be1d279f13a927ad1209501a223dc1e",
   "name": "Test User",
   "email": "testuser@example.com", 
   "email_verified": true
  }

The table below shows the meaning of claim.

Error Response

The authorization server also returns a JSON-formatted response when your request fails. Here is an example of error response:

HTTP/1.1 401 Unauthorized
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  WWW-Authenticate: Bearer realm="auth.api.ricoh",
                    error="invalid_token",
                    error_description="The access token was expired or invalid."
  {
    "error":"invalid_token",
    "error_description":"The access token was expired or invalid."
  }

Error responses include the following fields:

You might encounter the following errors:

ID Token

If the token request succeeds, your application can obtain an ID token. ID token is JWT (JSON Web Token) specified in RFC 7523. It is signed in accordance with the JWS format prescribed in RFC 7515. Applications that received the ID token MUST validate the ID token described in ID Token Validation.

Headers and Payload

Items included in the header part and payload part of ID Token are as follows:

ID Token Validation

Your application MUST validate the ID token in the following way:

1. Verify the signature of ID token.
2. Verify that the value of iss is https://auth.api.ricoh/v1.
3. Verify that the value of aud matches your application’s client ID.
4. Make sure expiry time (exp) has not passed.
5. Verify that the value of nonce matches what specified in the authentication request.

The public key for signature verification described in 1 is published in the keys endpoint (https://auth.api.ricoh/v1/discovery/keys) in the format of JWK Set. the keys endpoint sometimes has multiple keys published, so select the public key that has the same kid with the one in the header section of ID token. Because we do not change public keys frequently, your application can keep the public key information and reuse it. Please access the keys endpoint and acquire a new public key only when your application gets new ID token with different kid.

How to Manage Token Expiration

Your application needs to manage access token expiration. Access tokens offered with Authorization Code Grant expire in certain time. Also, the authorization server does not support refresh requests. In order to access the API after the expiration time of the token expired, it is necessary to redo the authentication request and token request again to obtain the access token. To detect the expiration of the access token, you can use one of the two methods below.

1. Calculate expiration time

Use the expires_in field of token response. You can calculate expiration time by using the field which represents the lifetime of the access token and the time you have received it. Let your application calculate and manage the expiration time of access token so that your application knows whether the access token has already expired or not.

2. Detect invalid_token error

Utilize invalid_token error responses. RICOH Cloud API services verify each access token in requests and return an invalid_token error response (with status code 401) when the access token has already expired. So, by detecting the error, your application detects token expiration.

Samples

• Video Chat Sample

See Also

• Authorization Code Grant API Reference
• OpenID Connect Core 1.0
• The OAuth 2.0 Authorization Framework (RFC6749)
• OAuth 2.0 Threat Model and Security Considerations
• JSON Web Token(JWK)
• JSON Web Signature (JWS)
• JSON Web Key (JWK)