Use the SCIM Interface to Integrate Oracle Identity Cloud Service with Custom Applications
This section provides answers to the following questions to help you understand how to use the SCIM interface to integrate Oracle Identity Cloud Service with custom applications:
Why Integrate with Custom Applications?
Let's say that you want to integrate your applications with Oracle Identity Cloud Service. Your applications are homegrown or aren’t listed in the App Catalog, and an AD Bridge or Provisioning Bridge can’t be used as a link between your applications and Oracle Identity Cloud Service.
A custom application is an application where the App Catalog or a bridge can’t be used to integrate it with Oracle Identity Cloud Service. By integrating your custom applications with Oracle Identity Cloud Service, from one centralized cloud service, you can provide SSO capabilities for your applications, and provision and synchronize your users between the applications and Oracle Identity Cloud Service.
The App Catalog has thousands of applications that integrate with Oracle Identity Cloud Service. For most applications, Oracle Identity Cloud Service provides single sign-on (SSO) and user provisioning capabilities. User provisioning is not only giving users initial access to these applications, but also managing the complete lifecycle of the relationship that the users have with the applications.
What Is SCIM?
In the past, it was common that applications used to have their own user management APIs. Because the APIs for each application behave in a certain way, the developer had to understand the APIs specific to each application to build integrations for the applications.
To integrate your custom applications with Oracle Identity Cloud Service, Oracle recommends that you use the System for Cross-domain Identity Management (SCIM). SCIM provides developers with an abstraction layer. If APIs for the applications are exposed through SCIM, then developers don't have to learn the APIs associated with each application because the JSON format of the APIs is common across all applications.
In addition to SCIM being an open specification that standardizes user and group management across applications, it allows for the automation of user and group provisioning. You can provision and synchronize data for your users and groups across multiple applications.
With SCIM, you can define HTTP endpoints to create, read, update, and delete resources for entities such as users and groups. You can also use SCIM to extend the schemas for your company’s users and groups. The SCIM specification defines a minimum set of attributes for the user schema, but this schema can be extended.
For example, suppose you need to provision the Employee ID custom attribute from the Oracle Identity Cloud
Service user schema to your custom application. You can extend the default user schema, add this attribute, and map it between Oracle Identity Cloud
Service and your application. The user schema in Oracle Identity Cloud
Service can now adhere to the attributes associated with your custom application's identity store.
The SCIM specification also defines security for any request that you make using HTTP endpoints. Security is defined by using a secure (HTTPS) protocol to establish communication between the endpoints and the applications with which you’re integrating, and requiring an authorization token that's used to access the request and perform the operations associated with it.
Use the following table to learn more about the SCIM specification:
| Item | URL |
|---|---|
| Core schema | https://tools.ietf.org/html/rfc7643 |
| Protocol | https://tools.ietf.org/html/rfc7644 |
| Definitions, overview, concepts, and requirements | https://tools.ietf.org/html/rfc7642 |
Why Use SCIM?
If you look at how integrations used to be built, developers had to understand the APIs exposed for each application. There was no consistency regarding how to represent an identity in these applications.
By using SCIM, there's now a common standard of how you represent an identity in every application. Because all applications comply with the SCIM format, there's a harmonious flow in terms of how these identities are represented. This makes it easier for an identity management cloud service such as Oracle Identity Cloud Service to integrate with these applications.
Having a common standard for representing identities in applications improves developers' work efficiency and productivity because developers don't have to spend time to learn the APIs for each application. From a corporate standpoint, the time it takes to develop an integration from an identity system to the application will be reduced significantly. You can now run automations for the integration because there's a standard in terms of how you represent an identity and how you integrate with that identity.
By exposing your custom application's identity store with a SCIM-based interface, you avoid having to develop a custom connector between your application and Oracle Identity Cloud Service. This can be time-consuming, costly, and can lead to heavy maintenance in a future upgrade.
SCIM automates the user identity lifecycle management process and increases the security of data associated with your company’s users and groups.
As your company grows, your users and groups increase. Through the day-to-day operations of your company, you may experience situations such as employee turnover or the memberships that your users have with your company’s groups may change. Your company’s user accounts, groups, and group memberships increase significantly.
Because SCIM is a standard, your company’s user and group data is stored in a consistent way and can be communicated as such across different apps (including your custom apps). You can automate the provisioning and deprovisioning process and have Oracle Identity Cloud Service function as a single point to manage permissions and group memberships. By transferring your company’s user and group data automatically, you mitigate the risk of inadvertent errors.
By implementing SCIM, you improve your company’s security. Through SSO, your company's employees no longer have to sign on to each of their accounts individually. You can ensure security policy compliance for your users and their access to your company's applications.
When your employees are terminated or leave your company, you want your company's offboarding process to be consistent. This way, there's no chance that your company's administrators will forget to deprovision user accounts for applications that contain sensitive data. With SCIM, when users depart from your company, your administrators can terminate the accounts in Oracle Identity Cloud Service, and have peace of mind because these accounts will also be suspended or deleted in your SCIM-enabled apps.
How Do You Use the Generic SCIM App Template?
In the App Catalog, there are thousands of applications that integrate with Oracle Identity Cloud Service. You may have your applications running on your premises or in the cloud, or you may be building your applications in different infrastructure systems such as Amazon Web Services or Oracle Cloud Infrastructure.
Oracle Identity Cloud Service has to provide not only integrations with the applications that are listed in the App Catalog, but also tools so that you can build integrations for your custom applications without developing code.
With the Generic SCIM App Template, you can configure your custom applications so that the SCIM APIs are exposed, and you don't have to develop a single line of code. All that's required is to go to the App Catalog and search for a SCIM-managed app template. To use this template, you only have to provide your endpoint URL and the details that Oracle Identity Cloud Service requires to connect to your application, and then map the attributes between your application and Oracle Identity Cloud Service.
With the Generic SCIM App Template, you can provision or synchronize users between your custom applications and Oracle Identity Cloud Service.
Description of the illustration scim-app-template-architeture.png
In this diagram, the Generic SCIM App Template has been configured to enable Oracle Identity Cloud Service to communicate with a custom application that has a SCIM-based interface. This interface uses REST API endpoints to provision and synchronize users between Oracle Identity Cloud Service and the custom application.
Before You Begin
Before you begin to use the Generic SCIM App Template:
-
Get access to an instance of Oracle Identity Cloud Service.
-
Make sure that you have the appropriate permissions to register applications and to manage security components in the Identity Cloud Service console.
-
Ensure that there’s HTTP(S) communication between Oracle Identity Cloud Service and the SCIM-based interface for your custom application.
-
Make sure that you have a basic knowledge of the SCIM specification.
Assign Administrator Roles to Your User Account
Although you have access to an instance of Oracle Identity Cloud Service, you must be assigned to the following administrator roles in Oracle Identity Cloud Service to use the Generic SCIM App Template in the Identity Cloud Service console:
-
Security administrator: To configure the security aspects of your Oracle Identity Cloud Service instance.
-
Application administrator: To add a custom application and use the Generic SCIM App Template.
To assign these administrator roles to your user account:
- Sign in to Oracle Identity Cloud Service with the credentials of your user account.
- In the Identity Cloud Service console, expand the Navigation Drawer, click Security, and then click Administrators.
- Expand the node for the Security Administrator role.
- Click Add, select the check box for your user account, and then click OK.
- Repeat steps 3 and 4 to assign the application administrator role to your user account.
Does Your Custom Application Have a SCIM-based Interface?
In this section, you learn what to do, based on whether your custom application has a SCIM-based interface.
If your custom application has this interface, then you can configure the Generic SCIM App Template to provision Oracle Identity Cloud Service users with your application. See Configure the Generic SCIM App Template.
If your custom application doesn't have this interface, then you can develop a custom SCIM gateway to act as the interface between Oracle Identity Cloud Service and your custom application. See How Do You Develop a Custom SCIM Gateway?
Configure the Generic SCIM App Template
In this section, you add an application using the Generic SCIM App Template, enable and configure connectivity for provisioning for your application, configure the application’s attribute mappings for provisioning, select the provisioning operations for your application, enable and configure synchronization for your application, and test your application to verify that users are provisioned to it.
Add an Application Using the Generic SCIM App Template
In this section, you use the Generic SCIM App Template to add an application.
Enable and Configure Connectivity for Provisioning for Your Application
In this section, you enable provisioning for your application and provide connectivity information for it. Oracle Identity Cloud Service uses this information to connect to your application's SCIM REST API endpoint for provisioning purposes.
Configure Attribute Mappings for Provisioning
You can change the default attributes mapped between Oracle Identity Cloud Service and your application's SCIM REST API.
- In the Provisioning tab of your application page, scroll to the Configure Attribute Mapping section, and then click Attribute Mapping. The Attribute Mapping window appears, and shows the default attribute mappings.
- In the Attribute Mapping window, add, modify, or remove attribute mappings, according to your application's SCIM user schema.
- Click OK.
Select Provisioning Operations
You can select which provisioning operations are supported by your application's SCIM REST APIs.
How Do You Develop a Custom SCIM Gateway?
If your custom application doesn't provide a SCIM-based interface, then you can develop a custom SCIM gateway to act as the interface between Oracle Identity Cloud Service and your custom application. This gateway exposes your application's identity store as SCIM-based REST APIs, and then you can use the Generic SCIM App Template to integrate Oracle Identity Cloud Service with your application for provisioning or synchronization purposes.
Before developing your custom SCIM gateway, if you're a new developer who isn’t familiar with the SCIM standard, then you must first understand the SCIM protocol. Then, see which identity attributes are available for your custom application and model them as SCIM-based attributes. Next, utilize open-standard libraries to expose your custom application’s APIs as SCIM APIs. Last, familiarize yourself with the create, read, update, and delete (CRUD) operations that you want your custom SCIM gateway to perform.
Supported Operations
User is a type of resource in the SCIM specification. To manage this resource, the SCIM gateway must expose REST API endpoints to enable operations such as creating, searching for, updating, and deleting users. The HTTP request for the operation that you want to perform and the HTTP response from that operation must be in a JSON format.
You can implement the following user operations:
| User Operation | Description | HTTP Operation | HTTP Endpoint |
|---|---|---|---|
| Create a User | Create a user account in your custom application. | POST |
https://app.example.com/scimgate/Users |
| Search Users | Obtain a list of all users with their attributes that are in your custom application. | GET |
https://app.example.com/scimgate/Users |
| Search a User | Retrieve information about a specific user and their attributes in your custom application. | GET |
https://app.example.com/scimgate/Users/<id> |
| Update a User Attribute | Update an attribute value of a user account in your custom application. | PUT |
https://app.example.com/scimgate/Users/<id> |
| Delete a User | Remove a user account from your custom application. | DELETE |
https://app.example.com/scimgate/Users/<id> |
How Do You Secure the Custom SCIM Gateway?
Because you don't want unauthorized users or clients to access your custom SCIM gateway, you must secure it. To do this, use an authorization token to protect the HTTP(S) endpoints of your gateway. This token will validate the user or client to allow them to make appropriate HTTP calls to the gateway endpoints. If the token isn't present or is invalid, then the endpoints will return a 401 HTTP response code because Oracle Identity Cloud
Service isn't authorized to access the endpoints.
Oracle Identity Cloud Service uses the administrator's user name and password, which are configured when you register your custom application, to request an access token from the custom SCIM gateway. Oracle Identity Cloud Service can then use this token to access the gateway endpoints as an authorization bearer header.
Sample Implementation of a Custom SCIM Gateway
Oracle provides a sample Node.js application that conforms to SCIM specifications, and which you can use to develop a custom SCIM gateway to integrate it with your custom application.
This custom gateway exposes HTTP endpoints to enable operations such as creating, searching for, updating, and deleting users. The custom gateway stores information about the users locally in the db.json file. This file has the JSON format.
Description of the illustration sample-app-architecture.png
The sample application uses express and body-parser packages. The server.js file implements a route for users' endpoints:
"...
var express = require('express')
var app = express()
var bodyParser = require('body-parser');
app.use(bodyParser.json());
var config = require('./config.js');
..."The routes/users.js file defines the SCIM REST API endpoints, and maps each endpoint to the corresponding JavaScript function:
"...
//Get operation for /Users endpoint
app.get('/scimgate/Users', users.findAll);
//Get operation for /Users/:id endpoint
app.get('/scimgate/Users/:id', users.findOne);
//Put operation for /Users endpoint
app.post('/scimgate/Users', users.create);
//Put operation for /Users endpoint
app.put('/scimgate/Users/:id', users.update);
//Delete operation for /Users endpoint
app.delete('/scimgate/Users/:id', users.delete);
..."The user.controller.js file implements JavaScript functions to create, read, update, and delete users in the local user store, represented by the userdb.json file:
"...
exports.findAll = function(req, res){
console.log('Entering findAll function.');
...
};
exports.findOne = function(req, res) {
console.log('Entering findOne function.');
...
};
exports.create = function(req, res){ console.log('Entering create function.');
...
};
exports.update = function(req, res){
console.log('Entering update function.');
...
};
exports.delete = function(req, res){ console.log('Entering delete function.');
...
};
..."The userdb.json file contains an array of users, and the structure of each user entry follows the SCIM specification standard, using a subset of the user attributes:
{
"resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "1",
"externalId": "1",
"userName": "user1@example.com",
"name": {
"formatted": "User 1 Name",
"familyName": "Name",
"givenName": "User 1"
},
"displayName": "User 1 DisplayName",
"active": true,
"password": "User1Password",
"emails": [
{
"value": "user1@example.com",
"type": "work",
"primary": true
}
]
}
]
}To authorize the client to make HTTP requests, the sample SCIM gateway application makes use of two environment variables that you must set before running the application: ADMINUSER and ADMINPASS. These variables represent the administrator's user name and password for your API authentication service. You provide values for these variables by setting up the run.sh shell script for Unix or Mac environments, or the run.bat batch script for Windows environments.
Oracle Identity Cloud
Service sends these administrative credentials in the form of an authorization header for all requests to authenticate the administrator’s credentials, and then accesses the custom SCIM gateway using the basic grant type.
You can modify the sample application's source code and implement other types of authentication methods to match your requirements.
You can also change the sample application's source code so that instead of contacting the local user store (represented by the userdb.json file), the new sample application contacts your application's identity store to create, read, update, and delete users.
Configure and Run the Custom SCIM Gateway Sample Application
In this section, you configure and run the custom SCIM gateway sample application to work with the GenericScim - Basic template.
Register the Custom SCIM Gateway Application
In this section, you register the custom SCIM gateway sample application with Oracle Identity Cloud Service.
SSLEnabled parameter to
false. If the server doesn't listen to the default HTTP(s) port
numner, then change the Port parameter to the corresponding port number
your application runs. After you update these parameters you can test connectivity
between the application and Oracle Identity Cloud
Service, and then activate the application.
to the right of the user, and then select