User Repository for SCIM Federation REST API

The Repository/ScimFed endpoint allows binding and managing a SCIM federated user repository (such as Microsoft Azure) to HID Authentication Service.

Note: The API version supported by HID Authentication Service is 10.2.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/configuration/{tenant}/v2/User/Repository/ScimFed	Retrieve the list of all SCIM federated user repositories
GET	Read	/configuration/{tenant}/v2/User/Repository/ScimFed/{uid}	Retrieve an SCIM federated user repository
POST	Create	/configuration/{tenant}/v2/User/Repository/ScimFed	Create an SCIM federated user repository
PUT	Replace	/configuration/{tenant}/v2/User/Repository/ScimFed/{uid}	Replace an SCIM federated user repository
DELETE	Delete	/configuration/{tenant}/v2/User/Repository/ScimFed/{uid}	Delete an SCIM federated user repository

Required Permissions

Function	Required Permissions
GET	Read reference data
GET ALL	Read reference data
CREATE	Read reference data LDAP Configuration
REPLACE	Read reference data LDAP Configuration
DELETE	Read reference data LDAP Configuration
TEST CONNECTION	Read reference data LDAP Configuration

Get All SCIM Federated User Repositories

GET /User/Repository/ScimFed

Copy

Sample Request URI

GET /configuration/{tenant}/v2/User/Repository/ScimFed

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
      "id": "DS_c",
      "meta":       {
         "resourceType": "UserRepository",
         "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/ScimFed/DS_c",
         "version": "1"
      },
      "name": "scim fed AAD",
      "type": "SCIM_FED_AD",
      "adminGroupAssignment":       {
         "type": "Group",
         "value": "USG_FTEMP",
         "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_FTEMP"
      },
      "roleAssignments":       [
                  {
            "roleId": "RL_AUDITV",
            "mappingCriteria": {"groupMembership": "475f23fa-ad47-4ca9-b535-9792c9494daa"}
         },
                  {
            "roleId": "RL_DEVADM",
            "mappingCriteria": {"groupMembership": "b94f8737-0885-4193-b91e-6249974d9df3"}
         }
      ],
      "provisioningAgentCredential":       {
         "type": "User",
         "value": "123",
         "$ref": "https://[base-server-url]/scim/tenant/v2/Users/123"
      },
      "userAuthenticationEndpoint":       {
         "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
         "clientId": "4fafef0d-79fc-470b-9e5e-7a1ed4fd549f"
      }
   }]
}

Get SCIM Federated User Repository

GET /User/Repository/ScimFed/{uid}

Copy

Sample Request

GET /configuration/{tenant}/v2/User/Repository/ScimFed/DS_a

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_a",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/Repository/ScimFed/DS_a",
      "version": "1"
   },
   "name": "scim fed AAD",
   "type": "SCIM_FED_AD",
   "adminGroupAssignment":    {
      "type": "Group",
      "value": "USG_FTEMP",
      "$ref": "https://[base-server-url]/scim/ONLINEBANK/v2/Groups/USG_FTEMP"
   },
   "roleAssignments":    [
            {
         "roleId": "RL_AUDITV",
         "mappingCriteria": {"groupMembership": "557bb2dc-290a-4c88-a288-720010f5d542"}
      },
            {
         "roleId": "RL_DEVADM",
         "mappingCriteria": {"groupMembership": "cb383a5c-0738-485c-a610-c5b3fa5025ca"}
      }
   ],
   "provisioningAgentCredential":    {
      "type": "User",
      "value": "123",
      "$ref": "https://[base-server-url]/scim/ONLINEBANK/v2/Users/123"
   },
   "userAuthenticationEndpoint":    {
      "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
      "clientId": "7b88e68a-ee84-4bdb-8a85-0449914ccf44"
   },
   "federatedAttributes":    [
            {
         "type": "AttributeType",
         "value": "ATR_EMAIL",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/ATR_EMAIL"
      },
            {
         "type": "AttributeType",
         "value": "LASTNAME",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/LASTNAME"
      },
            {
         "type": "AttributeType",
         "value": "ATR_MOBILE",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/ATR_MOBILE"
      },
            {
         "type": "AttributeType",
         "value": "FIRSTNAME",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/FIRSTNAME"
      }
   ]
}

Create SCIM Federated User Repository

POST /User/Repository/ScimFed

Copy

Sample Request URI

POST /configuration/{tenant}/v2/User/Repository/ScimFed

Copy

Sample Request

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_aad1",
   "name": "scim fed AAD",
   "type": "SCIM_FED_AD",
   "adminGroupAssignment":    {
      "value": "USG_FTEMP"
   },
   "provisioningAgentCredential": {
    "value": "123"
   },
   "userAuthenticationEndpoint":    {
        "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
        "clientId": "HIDauthnService"
    },
   "roleAssignments":    [
            {
         "roleId": "RL_AUDITV",
         "mappingCriteria": {
            "groupMembership": "475f23fa-ad47-4ca9-b535-9792c9494daa"
         }
      },
            {
         "roleId": "RL_DEVADM",
         "mappingCriteria": {
            "groupMembership": "b94f8737-0885-4193-b91e-6249974d9df3"
         }
      }
   ],
    "federatedAttributes": [ {
        "value": "LASTNAME"
    }, {
        "value": "FIRSTNAME"
    }, {
        "value": "ATR_MOBILE"
    }, {
        "value": "ATR_EMAIL"
    }]
}

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_aad1",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/ScimFed/DS_aad1",
      "version": "1"
   },
   "name": "scim fed AAD",
   "type": "SCIM_FED_AD",
   "adminGroupAssignment":    {
      "type": "Group",
      "value": "USG_FTEMP",
      "$ref": "https://[base-server-url]/configuration/tenant/v2/Groups/USG_FTEMP"
   },
   "roleAssignments":    [
            {
         "roleId": "RL_AUDITV",
         "mappingCriteria": {"groupMembership": "475f23fa-ad47-4ca9-b535-9792c9494daa"}
      },
            {
         "roleId": "RL_DEVADM",
         "mappingCriteria": {"groupMembership": "b94f8737-0885-4193-b91e-6249974d9df3"}
      }
   ],
   "provisioningAgentCredential":    {
      "type": "User",
      "value": "123",
      "$ref": "https://[base-server-url]/configuration/tenant/v2/Users/123"
   },
   "userAuthenticationEndpoint":    {
      "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
      "clientId": "HIDauthnService"
   },
   "federatedAttributes":    [
            {
         "type": "AttributeType",
         "value": "ATR_EMAIL",
         "$ref": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/ATR_EMAIL"
      },
            {
         "type": "AttributeType",
         "value": "LASTNAME",
         "$ref": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/LASTNAME"
      },
            {
         "type": "AttributeType",
         "value": "FIRSTNAME",
         "$ref": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/FIRSTNAME"
      },
            {
         "type": "AttributeType",
         "value": "ATR_MOBILE",
         "$ref": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/ATR_MOBILE"
      }
   ]
}

Update SCIM Federated User Repository

PUT /User/Repository/ScimFed/{uid}

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Copy

Sample Request URI

PUT /configuration/{tenant}/v2/User/Repository/ScimFed/DS_a

Copy

Sample Request

{
    "roleAssignments":    [
        {
            "roleId": "RL_AUDITV",
            "mappingCriteria": {"groupMembership": "557bb2dc-290a-4c88-a288-720010f5d542"}
        },
        {
            "roleId": "RL_DEVADM",
            "mappingCriteria": {"groupMembership": "cb383a5c-0738-485c-a610-c5b3fa5025ca"}
        },
        {
            "roleId": "RL_SSPADM",
            "mappingCriteria": {"groupMembership": "cb383a5c-0738-485c-a610-c5b3fa5025ca"}
        },
        {
            "roleId": "RL_SSPADM",
            "mappingCriteria": {"groupMembership": "557bb2dc-290a-4c88-a288-720010f5d542"}
        }
    ],
    "provisioningAgentCredential": {
        "value": "122"
    },
    "userAuthenticationEndpoint":    {
        "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
        "clientId": "2a18e6ca-08ja-p2e3-8a85-0evy14ccfea4"
    },
    "federatedAttributes":    [
        {
            "type": "AttributeType",
            "value": "FIRSTNAME"
        },
        {
            "type": "AttributeType",
            "value": "LASTNAME"
    }]}

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_a",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/Repository/ScimFed/DS_a",
      "version": "1"
   },
   "name": "scim fed AAD",
   "type": "SCIM_FED_AD",
   "adminGroupAssignment":    {
      "type": "Group",
      "value": "USG_FTEMP",
      "$ref": "https://[base-server-url]/scim/ONLINEBANK/v2/Groups/USG_FTEMP"
   },
   "roleAssignments":    [
            {
         "roleId": "RL_AUDITV",
         "mappingCriteria": {"groupMembership": "557bb2dc-290a-4c88-a288-720010f5d542"}
      },
            {
         "roleId": "RL_DEVADM",
         "mappingCriteria": {"groupMembership": "cb383a5c-0738-485c-a610-c5b3fa5025ca"}
      },
            {
         "roleId": "RL_SSPADM",
         "mappingCriteria": {"groupMembership": "cb383a5c-0738-485c-a610-c5b3fa5025ca"}
      },
            {
         "roleId": "RL_SSPADM",
         "mappingCriteria": {"groupMembership": "557bb2dc-290a-4c88-a288-720010f5d542"}
      }
   ],
   "provisioningAgentCredential":    {
      "type": "User",
      "value": "122",
      "$ref": "https://[base-server-url]/scim/ONLINEBANK/v2/Users/122"
   },
   "userAuthenticationEndpoint":    {
      "issuerUri": "<url of your Microsoft Azure AD or ADFS Oauth2 provider>",
      "clientId": "2a18e6ca-08ja-p2e3-8a85-0evy14ccfea4"
   },
   "federatedAttributes":    [
            {
         "type": "AttributeType",
         "value": "LASTNAME",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/LASTNAME"
      },
            {
         "type": "AttributeType",
         "value": "FIRSTNAME",
         "$ref": "https://[base-server-url]/configuration/ONLINEBANK/v2/User/AttributeType/FIRSTNAME"
      }
   ]
}

Delete SCIM Federated User Repository

DELETE /User/Repository/ScimFed/{uid}

If there are no users or groups bound to it, the datasource is deleted directly and the sessions for the provisioning agent are removed.
If the datasource does have bound users and groups, it is marked "to be deleted" and as a background process:
1. SearchUsers is called to find all users provisioned by the datasource and they are deleted (progressively to avoid impacting the service).
2. When all the users are deleted, the security groups bound to this datasource are deleted.
3. Then the datasource itself is deleted.

Important: As soon as a datasource is marked 'to be deleted':

You can no longer provision users with the associated provisioning agent.

All authentications are blocked for the users provisioned with this datasource and will return the failure response ‘REASON_USER_REPO_DELETED’:

Copy

Sample Response

HTTP/1.1 400 Bad Request
{
   "hid_failure":    {
      "reason": 60,
      "authType": "AT_LDAP"
   },
   "error_description": "Invalid grant: Resource owner username or password is invalid (User repository is deleted):Resource owner username or password is invalid",
   "error": "invalid_grant"
}

Copy

Sample Request URI

DELETE /configuration/{tenant}/v2/User/Repository/ScimFed/{uid}

Copy

Sample Request

DELETE /configuration/{tenant}/v2/User/Repository/ScimFed/DS_b

Copy

Sample Response

HTTP/1.1 204 No Content

Test Connection

POST /User/Repository/ScimFed/{uid}

Copy

Sample Request URI

POST /configuration/{tenant}/v2/User/Repository/ScimFed/{uid}

Copy

Sample Request

POST /configuration/{tenant}/v2/User/Repository/ScimFed/DS_a
{
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "TEST-CONNECTION"
    }  
}

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
   "attributes":    [
            {
         "name": "CONNECTION_SUCCESS",
         "value": "true"
      },
            {
         "name": "AUTHENTICATION_SUCCESS",
         "value": "true"
      }
   ]
}

Error Codes

Function	Use Case	HTTP Error	Error code
create SCIM_FED user	Using a session that does not match any provisioning agent.	500	9009 - There is no datasource with matching provisioningAgent.
add member to security group remove member from security group delete security group	Using a session that does not match any provisioning agent, on a group that is bound to a datasource	400	9009 - There is no datasource with matching provisioningAgent.
add member to security group remove member from security group update user status (active/disabled)	Not using the prov agent that provisioned the user.	400	9011 - User is bound to a datasource that does not match this session. Use the provisioning agent from the dedicated datasource.
add member to security group remove member from security group delete security group	Not using the prov agent that provisioned the security group.	400	9012 - Security Group is bound to a datasource that does not match this session. Use the provisioning agent from the dedicated datasource.
add member to security group remove member from security group delete security group	Using a provisioning agent on a security group that is not bound to a datasource. (= security group not created by a provisioning agent)	400	9013 - Security Group is not bound to a datasource.
add member to security group	Adding a non SCIM_FED User into a group bound to a datasource, using the provisioning agent for this datasource	400	9014 - Cannot add a non-SCIM_FED User into a security group bound to a datasource.