OAuth 2.0 (client credentials) as a token-based protocol for API authentication

[#1]

• Overview
• SCIM protocol
• Supported HTTP Methods
• Authentication
• Basic authentication
• OAuth 2.0
• OAuth client management page
• How to create an OAuth client
• How to get access token for OAuth
• Sample output
• Access IdentityIQ API
• Sample output
• Troubleshooting

Overview

The IdentityIQ API provides access to the IdentityIQ platform, allowing new opportunities for expanded innovation.

You can use your API to access IdentityIQ API endpoints, which allows to programmatically invoke IdentityIQ API to interact with objects within IdentityIQ.

This document provide insight to use OAuth 2.0 Authentication.

SCIM protocol

SCIM stands for System for Cross-Domain Identity Management, and it is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support through a standardized RESTful API service. It provides a platform neutral schema and extension model for representing users, groups and other resource types in JSON format.

Supported HTTP Methods

• GET
• POST
• PUT
• DELETE

Authentication

Basic authentication

Beginning in IdentityIQ version 7.0, Patch 2, basic authentication is used to allow access to the API. Basic authentication is a simple technique for enforcing access controls to API resources because it doesn’t require session IDs, cookies, or login pages but instead uses standard fields in the HTTP header. For more information on basic authentication, please  see https://tools.ietf.org/html/rfc1945#section-11 and https://www.ietf.org/rfc/rfc2617.txt. Support for basic authentication will continue to exist in future releases.

OAuth 2.0

OAuth 2.0 Authentication will be supported in IdentityIQ version 7.1. Versions prior to 7.1 only support basic authentication.

OAuth client management page

The OAuth Client Management page has the following tabs and options:

• OAuth Client Management tab — displays a list of the current OAuth clients.

     - Create Button — creates an OAuth client that has a proxy user with an associated secret.

     - Secret Details icon — displays the secret for the an OAuth client.

     - Actions icons — Edit, Delete, Regenerate Secret

• General Settings tab

     - Access Token Expiration In Seconds

 

How to create an OAuth client

     1. From the top menu, navigate to the Gear icon > Global Settings > API Authentication.

     2. On the OAuth Client Management tab, click Create.

     3. In the OAuth Client dialog enter a unique name for Client Name and then enter a user name or select a user from the drop-down list for the Proxy User.

     4. Click Save to save your new OAuth client.

After your create an OAuth client, you can use it with the associated secret to log in and access the token for that proxy user.

How to get access token for OAuth

When we are enabling OAuth authentication, we should get access token before invoking IdentityIQ API.

We should use the following details to get access token from IdentityIQ:

• client_id - will get client id from OAuth client management
• client_secret - will get client id from OAuth client management
• grant_type (client_credentials)
• Token URL - "http://localhost:8080/identityiq/oauth2/token"

Sample REST Client to get access token

Client client = ClientBuilder.newClient();   MultivaluedMap<String, String> formData = new MultivaluedHashMap();   formData.add("grant_type", grantType);   String secret = "Basic "+Base64.encodeBase64String(new String(clientID+":"+clientSecret).getBytes()); // we should use Base64 encode to encode client id and client secret   Response  response = (Response) client.target(tokenURL). // token URL to get access token   request(MediaType.APPLICATION_JSON). // JSON Request Type   header( "Authorization", secret ) // Authorization header goes here   .post(Entity.form(formData))  ;   // body with grant type   String output = response.readEntity(String.class); // reading response as string format Sample output "expires_in": 1200,   "token_type": "bearer",   "access_token":"original token"

Access IdentityIQ API

When OAuth authentication is enabled for IdentityIQ API, we should get access token before consuming API. After we receive access token from IIQ, will access API with access token.

Sample REST client to access IdentityIQ API

Client client = ClientBuilder.newClient();   Response response = (Response)client.target(apiURL). // API URL goes here (e.g. http://localhost:8080/identityiq/scim/v2/Applications/​{Application id/Name}   request(MediaType.APPLICATION_JSON). //Request type   accept(accepType). // Response access type - application/scim+json   header("Authorization", token).get(); // header with access token as authorization value   String output = response1.readEntity(String.class); // reading response as string format Sample output { "id": "2c9084ee5571ab87015571ac44810319", "schemas": [ "urn:ietf:params:scim:schemas:sailpoint:1.0:Application" ], "identAttr": {}, "applicationSchemas": [ { "value": "2c9084ee5571ab87015571ac4482031b", "$ref": "http://localhost:8080/iiq/scim/v2/Schemas/urn:ietf:params:scim:schemas:sailpoint:1.0:Application:Sch...", "type": "account" } ], "name": "HR_Employees", "features": [ "DIRECT_PERMISSIONS", "NO_RANDOM_ACCESS", "DISCOVER_SCHEMA" ], "owner": { "value": "2c9084ee5571ab87015571ac426d0316", "$ref": "http://localhost:8080/iiq/scim/v2/Users/2c9084ee5571ab87015571ac426d0316", "displayName": "HR_Employees App Owners" }, "type": "Delimited File Parsing Connector", "meta": { "lastModified": "2016-06-21T01:42:49.362-05:00", "created": "2016-06-21T01:36:03.074-05:00", "location": "http://localhost:8080/iiq/scim/v2/Applications/2c9084ee5571ab87015571ac44810319", "resourceType": "Application", "version": "W/\"1466491369362\"" } }

Troubleshooting

If you run into a problem, post it to the forum for help from the community. 

User does not have access error

Invalid_grant error

[smitha_sudarsanan1]

The SCIM calls are failing after upgrade to 8.4p1. Has anyone faced this issue?