OAuth2.0
Contents
OAuth 2.0 gCube Support
Since gCube 4.3, external application can perform operation on behalf of registered users. For instance, they can require user's credentials. For more information about the OAuth authorization framework please visit the official OAuth site. For technical details you could also check the OAuth 2.0 RFC. In the following, the needed steps to authorize third party applications to operate on user's behalf and the D4Science portals are going to be shown.
Step 1 - Configure your application
Authorized third party applications must be registered via a ... TODO.
They need to specify a redirect (or callback) uri (https is strongly suggested). This url must be absolute, and without arguments. Once the application is registered, it will have associate:
- a unique client identifier (client_id);
- a client secret which must be kept secret, as the name itself says (client_secret).
client_id: ab9d32c9-9425-42f1-99d7-50d68e651e9c client_secret: y9r93zDv4D
Both are needed to proceed with the OAuth 2.0 workflow.
Step 2 - Require an authorization code
Once the application is registered and configured, an authorization code can be requested. This code is not the final one needed to perform operations on user behalf, but is the one that will be exchanged for that in the next step. To require this code that has a very short time to live, the application must invoke the authorization service, which is gateway dependant. Once this call is executed, two things can happen
- the user is requested to perform the login, thus accepting the application operation and granting it;
- if there is a valid existing permission grant for the application, the login operation is by-passed and the redirect_uri is followed.
The parameters that need to be provided here are the following
Parameter | Description | Required |
---|---|---|
client_id | the client identifier associated to the application | yes |
redirect_uri | the redirect uri provided at registration phase | yes |
state | a unique string value hard to guess, needed to prevent CRSF attacks (e.g. AAedBEeF545sdfKef897) | yes |
scope | this field is optional. It can be specified to request (with the next step) an access token valid for a given
infrastructure scope. If missing, the scope will be choose by the user on credentials insertion. |
no |
This is an example in development environment
https://next.d4science.org/group/next/authorization?client_id=ab9d32c9-9425-42f1-99d7-50d68e651e9c&scope=%2Fgcube&redirect_uri=https%3A%2F%2Fwww.gcube-system.org%2Fdevelopers&state=7d12bf13-111c-4f46-ab06-9e9e08ad377b
If the user grants permissions to the application, a redirection to the redirect_uri is performed. Attached to the redirect_uri, two important url arguments are provided
- code: which is the OAuth 2.0 authorization code. It expires in 10 seconds;
- state: which is the same value provided by the application, which is in charge of checking that it is the same.
If, for any reason, the request fails, the redirect_uri is still followed but the url has attached the following parameters
- error: a code that states the type of error;
- error_description: a textual description of the actual error;
- state: which is the same value provided by the application, which is in charge of checking that it is the same.
Retrieving the authorization endpoint location
The previous authorization endpoint location is portal's gateway dependant and can be retrieved by using the icproxy service. For instance, in development environment the icproxy service is hosted at
node10-d-d4s.d4science.org/icproxy
The profile to be retrieved, which contains the AuthorisationServer endpoint, can be obtained as follows. Suppose you want to retrieve this information for the gCube Snapshots Gateway, then the call is the following
Which requires an authorization token. The returned profile is something like
<?xml version="1.0" encoding="UTF-8"?> <serviceEndpoints> <Resource version="0.4.x"> <ID>b1c5851f-1d47-4c60-8906-941ab859a334</ID> <Type>RuntimeResource</Type> <Scopes> <Scope>/gcube</Scope> </Scopes> ... <AccessPoint> <Description>AuthorisationServer where to authenticate external SmartGears services oAuth like</Description> <Interface> <Endpoint EntryName="AuthorisationServer">https://next.d4science.org/group/next/authorization</Endpoint> </Interface> </AccessPoint> </Profile> </Resource> </serviceEndpoints>
Step 3 - Exchange Authorization Code for an Access Token
This is the step in which the previously obtained code can be exchanged to obtain a real access token. This time, an http post method needs to be called. The request-body must contain the following parameters
Parameter | Description | Required |
---|---|---|
grant_type | The value of this field should always be authorization_code | yes |
code | the authorization code you received from the previous step. | yes |
redirect_uri | the same 'redirect_uri' value that you
passed in the previous step. |
yes |
client_id | the client identifier | yes |
client_secret | the client_secret associated to the application | yes |
The request must be performed by using a Content-Type of type application/x-www-form-urlencoded. For instance
POST /gcube-oauth/v2/accessToken HTTP/1.1
Host: www.socialnetworking-d-d4s.d4science.org
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=...&redirect_uri=https%3A%2F%2Fwww.gcube-system.org%2Fdevelopers&client_id=ab9d32c9-9425-42f1-99d7-50d68e651e9c&client_secret=...
In case of success, the response will contain a JSON object, having these properties:
- access_token: the obtained access token to use to perform operations on user's behalf;
- expires_in: the time to live of the token expressed in seconds;
- scope: in which scope the token is valid;
- token_type: that is "Bearer".
In case of failures, instead, the returned object will contain:
- error : an error string according the oauth 2.0 RFC.
- error_description : a text description for the error.
Retrieving the gcube-oauth endpoint location
The host to contact to perform this call can be again discovered via the icproxy service. This time the url will be something like
http://node10-d-d4s.d4science.org/icproxy/gcube/service/GCoreEndpoint/Portal/oauth?gcube-token=35eaf849-43d3-439c-a3bc-2f7c355c0f67
A resource profile is returned which contains the property jersey-servlet to be retrieved. In development environment its current value is