# OauthAuthenticationApi All URIs are relative to *http://localhost* Method | HTTP request | Description ------------- | ------------- | ------------- [**oAuthAuthorize**](OauthAuthenticationApi.md#oAuthAuthorize) | **GET** /api/rainbow/authentication/v1.0/oauth/authorize | 1 - OAuth Authorization Request [**oAuthToken**](OauthAuthenticationApi.md#oAuthToken) | **POST** /api/rainbow/authentication/v1.0/oauth/token | 2 - OAuth Access Token Request # **oAuthAuthorize** > OAuthAuthorizeSuccess oAuthAuthorize(contentType, responseType, clientId, redirectUri, scope, state) 1 - OAuth Authorization Request This endpoints allows applications to get authorization from Rainbow users to use Rainbow APIs with their account. This delegation of access can be performed using OAuth 2.0 **Authorization code** grant or **Implicit** grant. While both OAuth 2.0 Authorization Code grant and Implicit grant are supported by Rainbow, Authorization Code grant is **recommended** as it is more secure. Implicit grant is recommended for browser applications implemented in JavaScript that can't provide a backend server handling the token exchange flow of OAuth Authorization Code grant. Indeed, such applications should not embed appSecret in their source code for security reasons, and Implicit grant allow them to retrieve the OAuth access token without sending the appSecret to Rainbow server (redirect_uri is the only security available with this flow). The limitation of implicit grant is that only an access token is returned, which has a limited lifetime and can't be renewed. Application has to execute again the whole Implicit grant flow to retrieve a new access token. To enable Implicit grant for an application, the application's setting `enableOAuthImplicitGrant` has to be set to true (it is disabled by default). For more information, see the OAuth 2.0 RFC related to authorization endpoint: - <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1</a> for Authorization Code grant, - <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">section 4.2.1</a> for Implicit grant. Note that Rainbow applications are named **client** in OAuth 2.0 RFC. ### 1. Authorize request for Authorization code grant The OAuth **Authorization Code** Grant flow is detailed in the following sequence diagram. This GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint addresses points 1 to 7 of this diagram for Authorization code grant flow (points 8 to 9 are addressed by POST /api/rainbow/authentication/v1.0/oauth/token endpoint, see related <a href=\"#api-OAuth_Authentication-OAuthToken\">documentation</a>). ![Failed to load diagram :-(](img/oauth_authorization_code_flow_sd.png \"OAuth Authorization Code Grant sequence diagram\") Details about the sequence diagram: - (1) User is on application website - (1) User accesses to application content that needs data from Rainbow, or application allows to login with Rainbow, … (use case depends of the application needs) - (2) Application redirects to OAuth authorize endpoint on Rainbow authentication server. Some query string parameters are provided in the query (defined by <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">OAuth 2.0 RFC</a>): - `response_type`: \"**code**\" for requesting an authorization code (authorization code grant) - `client_id`: the application identifier (appId) - `redirect_uri`: application\\'s backend endpoint where the authorization code will be sent. <br/> It has to use TLS for security reasons, as the authorization code is exchanged between Rainbow and the application\\'s backend through the browser. - `scope`: scope of the access requested by the application. <br/> Currently, only \"all\" is supported (meaning that the application will have full access on all the Rainbow APIs). <br/> In a next step, scopes will be defined so that the application can request restricted scopes (filestorage, bubble management, channels, …) - `state`: a \"random\" value sent by the client to maintain a state between the request and the callback. Can be used to protect against cross-site request forgery attacks (CSRF). - (3) Rainbow authentication server checks that the `client_id` sent in query parameter in (2) corresponds to a valid application in the database. - If so, Rainbow authentication server redirects user\\'s browser to Rainbow login page - Otherwise, an error is returned (if redirect_uri is provided, user\\'s browser is redirected to this uri and the error is sent in query parameters) - (4) User enters his credentials on login page and submit the form. Rainbow authentication server checks in the database if user credentials are valid. - (5) If so, Rainbow authentication server redirects user\\'s browser to consent page - Otherwise, Rainbow authentication server redirects again user\\'s browser to login page with an error which is displayed for the user - (6) User authorize the application to access Rainbow APIs in his name. The form is submitted on Rainbow authentication server. - (7) If the user authorized, Rainbow authentication server generates an authorization code and redirects user\\'s browser to application backend\\'s `redirect_uri` (the one provided in query parameters in (2)). Note that `redirect_uri` must be one of the configured `oauthRedirectUris` in the application, otherwise an error is returned. The following data are returned in query parameters of the redirection uri (defined by <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.2\">OAuth 2.0 RFC</a>): - `code`: the authorization code that can be exchanged against an access token and a refresh token using <a href=\"#api-OAuth_Authentication-OAuthToken\">token endpoint</a>. Authorization code has a short lifetime (10 minutes) and can only be used once. - `state`: if state was provided in (2), this value is returned (otherwise a random value is returned). - If the user declined, Rainbow authentication server redirects user\\'s browser to application backend\\'s `redirect_uri` with an error in query parameters. Once the application has the authorization code, it has to exchange it against an access token and a refresh token using POST /api/rainbow/authentication/v1.0/oauth/token endpoint, points 8 and 9 of the sequence diagram (see <a href=\"#api-OAuth_Authentication-OAuthToken\">documentation</a> of this endpoint for more information). ### 2. Authorize request for Implicit grant The OAuth **Implicit** Grant flow is detailed in the following sequence diagram. Unlike Authorization Code grant flow, this GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint is the only one to be used by the application to retrieve the OAuth access token. ![Failed to load diagram :-(](img/oauth_implicit_flow_sd.png \"OAuth Implicit Grant sequence diagram\") Details about the sequence diagram: - (1) User uses the web application on his browser - (1) User accesses to web application content that needs data from Rainbow, or web application allows to login with Rainbow, … (use case depends of the application needs) - (2) Application redirects to OAuth authorize endpoint on Rainbow authentication server. Some query string parameters are provided in the query (defined by <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">OAuth 2.0 RFC</a>): - `response_type`: \"**token**\" for requesting an access token (implicit grant) - `client_id`: the application identifier (appId) - `redirect_uri`: web application\\'s endpoint where the authorization code will be sent. - `scope`: scope of the access requested by the application. <br/> Currently, only \"all\" is supported (meaning that the application will have full access on all the Rainbow APIs). <br/> In a next step, scopes will be defined so that the application can request restricted scopes (filestorage, bubble management, channels, …) - `state`: a \"random\" value sent by the client to maintain a state between the request and the callback. Can be used to protect against cross-site request forgery attacks (CSRF). - (3) Rainbow authentication server checks that the `client_id` sent in query parameter in (2) corresponds to a valid application in the database. - If so, Rainbow authentication server redirects user\\'s browser to Rainbow login page - Otherwise, an error is returned (if redirect_uri is provided, user\\'s browser is redirected to this uri and the error is sent in fragment component of this redirection uri) - (4) User enters his credentials on login page and submit the form. Rainbow authentication server checks in the database if user credentials are valid. - (5) If so, Rainbow authentication server redirects user\\'s browser to consent page - Otherwise, Rainbow authentication server redirects again user\\'s browser to login page with an error which is displayed for the user - (6) User authorize the application to access Rainbow APIs in his name. The form is submitted on Rainbow authentication server. - (7) If the user authorized, Rainbow authentication server generates an access token and redirects user\\'s browser to web application\\'s `redirect_uri` (the one provided in query parameters in (2)). Note that `redirect_uri` must be one of the configured `oauthRedirectUris` in the application, otherwise an error is returned. The following data are returned in **fragment** component of the redirection uri (defined by <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.2\">OAuth 2.0 RFC</a>): - `access_token`: the access token that can be used by the application to use Rainbow APIs, - `token_type`: the type of token returned (\"**access_token**\"), - `expires_in`: the lifetime of the access token (in seconds), - `state`: if state was provided in (2), this value is returned (otherwise a random value is returned). - If the user declined, Rainbow authentication server redirects user\\'s browser to application\\'s `redirect_uri` with an error in fragment component. > Once the application has the access token, it can use it to use Rainbow APIs with the account of the related Rainbow user. ### Example ```java // Import classes: import com.ale.rainbow.s2s.client.auth.ApiClient; import com.ale.rainbow.s2s.client.auth.ApiException; import com.ale.rainbow.s2s.client.auth.Configuration; import com.ale.rainbow.s2s.client.auth.models.*; import com.ale.rainbow.s2s.client.auth.api.OauthAuthenticationApi; public class Example { public static void main(String[] args) { ApiClient defaultClient = Configuration.getDefaultApiClient(); defaultClient.setBasePath("http://localhost"); OauthAuthenticationApi apiInstance = new OauthAuthenticationApi(defaultClient); String contentType = "contentType_example"; // String | application/x-www-form-urlencoded String responseType = "responseType_example"; // String | Desired grant type to use for authorize endpoint.
To be set to: - ```code``` if Authorization Code grant is used, - ```token``` if Implicit grant is used. For more information, details are available in the OAuth 2.0 RFC, section 3.1.1 and section 4.1.1 (Authorization Code grant) or section 4.2.1 (Implicit grant). String clientId = "clientId_example"; // String | Unique identifier of the application requesting the authorization (also documented as ```appId``` in Rainbow APIs documentation).

For more information, details are available in the OAuth 2.0 RFC, section 2.2 and section 4.1.1 (Authorization Code grant) or section 4.2.1 (Implicit grant). String redirectUri = "redirectUri_example"; // String | Application's endpoint URI where the user-agent will be redirected with the authorization code (Authorization Code grant) or access token (Implicit grant) if the user grants access to the application.
Errors are redirected to this endpoint as well, for example in the case the user declines access to the application.

If ```redirect_uri``` parameter is specified, it must be one of the URIs defined in application's ```oauthRedirectUris``` parameter, otherwise the user-agent is redirected to the specified redirect_uri with an error and error_description parameters in query string (error=invalid_client&error_description=Invalid client: `redirect_uri` does not match client value).

If ```redirect_uri``` parameter is not specified, the first URI defined in application's ```oauthRedirectUris``` parameter is used.
=> Application's ```oauthRedirectUris``` parameter must be configured to allow the application to use OAuth 2.0 authorization grant.

If Authorization Code grant is used, this endpoint should use TLS for security reasons, as sensitive data are sent to application's endpoint through a public network.

For more information, details are available in the OAuth 2.0 RFC, section 3.1.2 and section 4.1.1 (Authorization Code grant) or section 4.2.1 (Implicit grant). String scope = "scope_example"; // String | The scope of the Rainbow API access requested by the application.
For now, only ```all``` is implemented (i.e. application has access to all the Rainbow APIs).

For more information, details are available in the OAuth 2.0 RFC, section 3.3 and section 4.1.1 (Authorization Code grant) or section 4.2.1 (Implicit grant). String state = "state_example"; // String | A random string that can be provided by the application to maintain state between the authorize request and the redirection to redirect_uri endpoint (state is sent back by Rainbow authentication server to redirect_uri endpoint).
This should be used by the application to prevent against cross-site request forgery (CSRF).

For more information, details are available in the OAuth 2.0 RFC, section 4.1.1.
For more information regarding cross-site request forgery (CSRF) threat, details are available in the section 10.12. try { OAuthAuthorizeSuccess result = apiInstance.oAuthAuthorize(contentType, responseType, clientId, redirectUri, scope, state); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling OauthAuthenticationApi#oAuthAuthorize"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **contentType** | **String**| application/x-www-form-urlencoded | **responseType** | **String**| Desired grant type to use for authorize endpoint. <br/> To be set to: - ```code``` if Authorization Code grant is used, - ```token``` if Implicit grant is used. For more information, details are available in the OAuth 2.0 RFC, <a href=\"https://tools.ietf.org/html/rfc6749#section-3.1.1\">section 3.1.1</a> and <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1 (Authorization Code grant)</a> or <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">section 4.2.1 (Implicit grant)</a>. | **clientId** | **String**| Unique identifier of the application requesting the authorization (also documented as ```appId``` in Rainbow APIs documentation). <br/> <br/> For more information, details are available in the OAuth 2.0 RFC, <a href=\"https://tools.ietf.org/html/rfc6749#section-2.2\">section 2.2</a> and <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1 (Authorization Code grant)</a> or <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">section 4.2.1 (Implicit grant)</a>. | **redirectUri** | **String**| Application's endpoint URI where the user-agent will be redirected with the authorization code (Authorization Code grant) or access token (Implicit grant) if the user grants access to the application. <br/> Errors are redirected to this endpoint as well, for example in the case the user declines access to the application. <br/> <br/> If ```redirect_uri``` parameter is specified, it must be one of the URIs defined in application's ```oauthRedirectUris``` parameter, otherwise the user-agent is redirected to the specified redirect_uri with an error and error_description parameters in query string (error=invalid_client&error_description=Invalid client: `redirect_uri` does not match client value). <br/> <br/> If ```redirect_uri``` parameter is not specified, the first URI defined in application's ```oauthRedirectUris``` parameter is used. <br/> => Application's ```oauthRedirectUris``` parameter must be configured to allow the application to use OAuth 2.0 authorization grant. <br/> <br/> If Authorization Code grant is used, this endpoint should use TLS for security reasons, as sensitive data are sent to application's endpoint through a public network. <br/> <br/> For more information, details are available in the OAuth 2.0 RFC, <a href=\"https://tools.ietf.org/html/rfc6749#section-3.1.2\">section 3.1.2</a> and <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1 (Authorization Code grant)</a> or <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">section 4.2.1 (Implicit grant)</a>. | [optional] **scope** | **String**| The scope of the Rainbow API access requested by the application. <br/> For now, only ```all``` is implemented (i.e. application has access to all the Rainbow APIs). <br/> <br/> For more information, details are available in the OAuth 2.0 RFC, <a href=\"https://tools.ietf.org/html/rfc6749#section-3.3\">section 3.3</a> and <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1 (Authorization Code grant)</a> or <a href=\"https://tools.ietf.org/html/rfc6749#section-4.2.1\">section 4.2.1 (Implicit grant)</a>. | [optional] **state** | **String**| A random string that can be provided by the application to maintain state between the authorize request and the redirection to redirect_uri endpoint (state is sent back by Rainbow authentication server to redirect_uri endpoint). <br/> This should be used by the application to prevent against cross-site request forgery (CSRF). <br/> <br/> For more information, details are available in the OAuth 2.0 RFC, <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.1\">section 4.1.1</a>. <br/> For more information regarding cross-site request forgery (CSRF) threat, details are available in the <a href=\"https://tools.ietf.org/html/rfc6749#section-10.12\">section 10.12</a>. | [optional] ### Return type [**OAuthAuthorizeSuccess**](OAuthAuthorizeSuccess.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: Not defined - **Accept**: application/json, application/unknown ### HTTP response details | Status code | Description | Response headers | |-------------|-------------|------------------| **200** | successful operation | - | # **oAuthToken** > OAuthTokenSuccess oAuthToken(body) 2 - OAuth Access Token Request This endpoints allows applications to get an access token allowing them to use Rainbow APIs with the account of the related Rainbow user. Access token has a short lifetime (1 hour). A refresh token is issued as well, allowing applications to refresh their access token (and such avoiding the application to request user authorization again with GET /api/rainbow/authentication/v1.0/oauth/authorize). The token endpoint can be used: 1. To exchange the authorization code against an access token and a refresh token, 2. To get a new access token using the refresh token (to be used when the access token has expired). ## 1. Exchange the authorization code against an access token and a refresh token For more information, see the <a href=\"https://tools.ietf.org/html/rfc6749#section-4.1.3\">OAuth 2.0 RFC, section 4.1.3</a> related to the use of this endpoint to exchange the authorization code against an access token and a refresh token. The OAuth Access Token Request flow is detailed in the following sequence diagram. This POST /api/rainbow/authentication/v1.0/oauth/token endpoint addresses points 8 to 9 of this diagram (points 1 to 7 are addressed by GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint, see related <a href=\"#api-OAuth_Authentication-OAuthAuthorize\">documentation</a>). ![Failed to load diagram :-(](img/oauth_authorization_code_flow_sd.png \"OAuth Authorization Code Grant sequence diagram\") Details about the sequence diagram: - (8) application\\'s backend exchanges the authorization code it retrieved in (7) against an access token and a refresh token. For that, it calls the OAuth token endpoint on Rainbow authentication server. It has to provide: - The header Authorization with Basic &lt;base64encode(`client_id`:`client_secret`)&gt;. This request has to be done from the application''s backend so that the client_secret (appSecret) remains confidential. Example of base64 calculation: ``` base64(\"78e98ee09bad11e8b8edebb50d679df6:2UrOcs3agk34zaV3Jsf01vM54iLyqwBEpnv5vJr72D9cE5wMVQeEe3BM7IxzyyJD\") = <i>NzhlOThlZTA5YmFkMTFlOGI4ZWRlYmI1MGQ2NzlkZjY6MlVyT2NzM2FnazM0emFWM0pzZjAxdk01NGlMeXF3QkVwbnY1dkpyNzJEOWNFNXdNVlFlRWUzQk03SXh6eXlKRA==</i> ``` - In the body the parameters (x-www-form-urlencoded): - `grant_type`: must be set to \"**authorization_code**\" for an exchange of an authorization code against an access token and a refresh token - `code`: the authorization code sent by Rainbow authentication server in (7) - `redirect_uri`: the redirect_uri parameter, must be the same than the one used to retrieve the authorization code (the one sent in (2)) - (9) Rainbow authentication server checks that the application\\'s credentials are valid by extracting client_id and client_secret from the Authorization header and comparing them to the appId and appSecret stored in the database. Then it checks that the provided authorization code is valid, has well been generated for this application and redirect_uri matches the one sent in (2). Provided authorization code is revoked, as it can only be used once. - If everything is valid, Rainbow authentication server generates an access token and a refresh token that it stores in the database and returns in the body of the HTTP response to the application\\'s backend. - Otherwise, a body with an error message is returned to the application\\'s backend. - (10) With the access token received from the Rainbow authentication server in (9), the application can use it to call Rainbow APIs in the name of the user. For that, it calls the Rainbow APIs with the header Authorization Bearer <access_token>. ### 2. Refresh an access token Access token has a short lifetime (1 hour). If the application tries to use an expired access token for a request on Rainbow API, an error 401 Unauthorized is returned. Access token can be renewed using the refresh token, this avoids the application to redo the whole OAuth authorization code flow. For more information, see the <a href=\"https://tools.ietf.org/html/rfc6749#section-6\">OAuth 2.0 RFC, section 6</a> related to the refresh of an access token. The OAuth Refresh Access Token flow is detailed in the following sequence diagram. ![Failed to load diagram :-(](img/oauth_refresh_token_flow_sd.png \"OAuth Refresh Access Token sequence diagram\") Details about the sequence diagram: - (1) User is on application website - (1) User accesses to application content that needs data from Rainbow (use case depends of the application needs). The application has already an OAuth access token and a refresh token retrieved using the authorization code grant described in \"*OAuth Authorization Code Grant sequence diagram*\". - (1) Application calls the Rainbow API (whatever the portal is) to access Rainbow user data. It provides the header `Authorization: Bearer &lt;access_token&gt;` in the request. - (2) Rainbow API portal checks the validity of the access token (existing, not expired). - (2) If the access token is expired, an error 401 Unauthorized is returned. The application needs to renew the access token. - (3) [optional, depends of the application implementation] If the application is executed in the browser (JavaScript), it needs to request its backend to get a new access token. If the request to Rainbow API is already performed in the application\\'s backend, the backend itself can renew the access token. - (4) Application\\'s backend calls the OAuth token endpoint on Rainbow authentication server. It has to provide: - The header Authorization with Basic &lt;base64(`client_id`:`client_secret`)&gt;. This request has to be done from the application\\'s backend so that the client_secret (appSecret) remains confidential. Example of base64 calculation: ``` base64(\"78e98ee09bad11e8b8edebb50d679df6:2UrOcs3agk34zaV3Jsf01vM54iLyqwBEpnv5vJr72D9cE5wMVQeEe3BM7IxzyyJD\") = <i>NzhlOThlZTA5YmFkMTFlOGI4ZWRlYmI1MGQ2NzlkZjY6MlVyT2NzM2FnazM0emFWM0pzZjAxdk01NGlMeXF3QkVwbnY1dkpyNzJEOWNFNXdNVlFlRWUzQk03SXh6eXlKRA==</i> ``` - In the body the parameters (x-www-form-urlencoded) - `grant_type`: must be set to \"**refresh_token**\" to request a new access token using the refresh token - `refresh_token`: the refresh token sent by Rainbow authentication server - (5) Rainbow authentication server checks that the client credentials are valid by extracting client_id and client_secret from the Authorization header and comparing them to the appId and appSecret stored in the database. Then it checks that the provided refresh token is valid, not expired, and has well been generated for this application. - If everything is valid, Rainbow authentication server generates a new access token and a new refresh token and return them in the body of the HTTP response to the application\\'s backend. - Otherwise, a body with an error message is returned to the application\\'s backend. - (6) The application updates its access token and refresh token in its own storage. In the case the applicationD is running in the browser, the backend returns the new access token to its frontend. - (7) The application redo the same API request to Rainbow portal done in (1), with the newly generated access token. - (8) Rainbow API portal checks the validity of the access token. As the access token is now valid, the Rainbow API performs the requested operation / returns the requested data. ### Example ```java // Import classes: import com.ale.rainbow.s2s.client.auth.ApiClient; import com.ale.rainbow.s2s.client.auth.ApiException; import com.ale.rainbow.s2s.client.auth.Configuration; import com.ale.rainbow.s2s.client.auth.models.*; import com.ale.rainbow.s2s.client.auth.api.OauthAuthenticationApi; public class Example { public static void main(String[] args) { ApiClient defaultClient = Configuration.getDefaultApiClient(); defaultClient.setBasePath("http://localhost"); OauthAuthenticationApi apiInstance = new OauthAuthenticationApi(defaultClient); OAuthToken body = new OAuthToken(); // OAuthToken | try { OAuthTokenSuccess result = apiInstance.oAuthToken(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling OauthAuthenticationApi#oAuthToken"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **body** | [**OAuthToken**](OAuthToken.md)| | ### Return type [**OAuthTokenSuccess**](OAuthTokenSuccess.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: application/json, application/unknown ### HTTP response details | Status code | Description | Response headers | |-------------|-------------|------------------| **200** | successful operation | - |