IDP API : OAuth2

API Title : OAuth2 APIs for token requests/validation with IDP Service
API Version: v1
RBAC Policy: Token authorization API requests will require user authentication, and the authenticated user will need to authorize each scope that is being requested by the app. Token grant and validation requests will need HTTP Basic authentication using app's registered client ID and secret (if any, blank otherwise). Additionally, for token grant requests, client ID and redirect url need to match the values in original authorization request for grant code.

oAuth2 Token Authorization

GET oauth/authorize?client_id={clientId}&response_type={responseType}&redirect_uri={redirectUrl}

request a token authorization approval from authenticated user

• clientId : app's registration client UUID issued by IDP
• responseType : valid values are code (authorization code grant), or token (implicit token grant)
• redirectUrl : url to redirect the user to with response of authorization request

this request will redirect user to authentication login page for user to login and then approve authorization to requested scopes for the registered app (determined based on clientId)

REQUEST:

GET /oauth/authorize?client_id=test.endpoint.client&response_type=code&redirect_uri=http://localhost HTTP/1.1
Host: if-idp.appspot.com
Authorization: Basic dXNlcjpwYXNzd29yZA==
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

RESPONSE:

HTTP/1.1 302 Found
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://if-idp.appspot.com/idp/login
Date: Sat, 13 Feb 2016 03:20:17 GMT
Content-Type: text/html

GET {redirectUrl}?code={authorizationCode}

redirection after successful token authorization approval for response type code

• redirectUrl : the redirect url provided by app in the original token authorization request
• authorizationCode : user approval authorization code to use with token grant request

EXAMPLE:

http://localhost/?code=66d92abe-6e6d-4678-9055-b249f566c4f7

GET {redirectUrl}#access_token={accessToken}&token_type=bearer&expires_in={validitySecs}&scope={scopes}

redirection after successful token authorization approval for response type token

• redirectUrl : the redirect url provided by app in the original token authorization request
• accessToken : implicit grant of access token based on user approval
• validitySecs : validity of the token in seconds
• scopes : list of entitlements that the endpoint app is approved for

EXAMPLE:

http://localhost/#access_token=7405217b-7483-4355-9520-c957a19ceb89&token_type=bearer&expires_in=3599&scope=endpoint

oAuth2 Token Grant

POST /oauth/token

request token grant based on authorization code
REQUEST:

POST /oauth/token HTTP/1.1
Host: if-idp.appspot.com
Authorization: Basic dGVzdC5vYXV0aDIuY29kZS5jbGllbnQ6
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=bcc3d83b-d38a-4bd0-a816-4438e29fdd00&redirect_uri=http%3A%2F%2Flocalhost

• Must have Authorization header for HTTP Basic authentication using "client-ID:secret" format (if secret was not registered for the app, use "")
• client ID must match the value used in client_id parameter with original token authorization request
• Content-Type has to be application/x-www-form-urlencoded
• parameter grant_type should be authorization_code
• parameter code should be the authorization code provided in response to original token authorization request with response type code
• parameter redirect_uri should match the value used in redirect_uri parameter with original token authorization request

RESPONSE:

{
    "access_token": "95ef2df7-7a77-4340-b8b0-be465094a475",
    "token_type": "bearer",
    "refresh_token": "f0119aa9-9417-41fe-9935-7b90fee2cd96",
    "expires_in": 3599,
    "scope": "endpoint"
}

oAuth2 Token Refresh

POST /oauth/token

get new access token by re-using refresh token grant from previous token authorization approval
REQUEST:

POST /oauth/token HTTP/1.1
Host: if-idp.appspot.com
Authorization: Basic dGVzdC5vYXV0aDIuY29kZS5jbGllbnQ6
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=f0119aa9-9417-41fe-9935-7b90fee2cd96

• Must have Authorization header for HTTP Basic authentication using "client-ID:secret" format (if secret was not registered for the app, use "")
• client ID must match the value used in client_id parameter with original token authorization request
• Content-Type has to be application/x-www-form-urlencoded
• parameter grant_type should be refresh_token
• parameter refresh_token should be the refresh token provided in response to initial token grant request for grant type authorization_code

RESPONSE:

{
    "access_token": "7ab13d7f-674a-42c1-a9bb-ad645afcf817",
    "token_type": "bearer",
    "refresh_token": "f0119aa9-9417-41fe-9935-7b90fee2cd96",
    "expires_in": 3599,
    "scope": "endpoint"
}

oAuth2 Token Validation

POST /oauth/check_token

validate a token and get user details
REQUEST:

POST /oauth/check_token HTTP/1.1
Host: if-idp.appspot.com
Authorization: Basic dGVzdC5vYXV0aDIuY29kZS5jbGllbnQ6
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

token=14f174df-2463-418e-bfa3-d152fff2c9c0

• Must have Authorization header for HTTP Basic authentication using "client-ID:secret" format
• an ENDPOINT app can only validate token issued to them (i.e. token has same app's client ID)
• Content-Type has to be application/x-www-form-urlencoded
• parameter token should be the value of access_token provided in response to token grant requests

RESPONSE:

{
    "org_id": "devnet-alpha.integratingfactor.com",
    "exp": 1455701781,
    "user_name": "385bc9b7-75aa-4e73-ab2c-ad06f9a76acf",
    "org_roles": [
        "USER"
    ],
    "scope": [
        "registrar",
        "validation"
    ],
    "authorities": [
        "ROLE_USER"
    ],
    "family_name": "Bhadoria",
    "preferred_username": "amit",
    "client_id": "developer.integratingfactor.com",
    "given_name": "Amit"
}