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 ActivID AS.

See also Using Microsoft Azure as a SCIM Federated Repository.

Note: The API version supported by ActivID AS 8.6 is 3.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.

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.