WorkBoard SCIM Implementation
Scope
WorkBoard supports user management and organizational hierarchy from two perspectives.
The first is the individual reporting structure. This is created by passing the user’s managerEmailAddress or managerID as an attribute in the SCIM API call payload.
WorkBoard does not support Just-In-Time provisioning. This means that if you provision a user with their manager identified and the manager is not also provisioned, we will not automatically provision the manager. The first sync-cycle may look incomplete. This is expected, and once the second sync cycle is complete it will look correct.
The second is the teaming framework. WorkBoard SCIM API does not currently support adding, updating, or deleting Teams from the Groups set up in the Identity Provider (IDP). We have plans to introduce this as part of our roadmap. Ask your WorkBoard Customer Success Manager for more details.
The scope of this document is to discuss user attribute schema, implementation details including user hierarchy, and authentication.
Authentication
A WorkBoard Administrator can send a request to WorkBoard for the SCIM token. Once this token is generated, it will be passed as the bearer token in the authorization header.
The IDP stores this token for all future SCIM API calls whenever any user is added, updated or deleted in the IDPs portal.
Note: WorkBoard SCIM API does not support DELETE requests. We process all DELETE calls as DISABLE.
The SCIM API token generated will encapsulate organization ID that will help us to direct the API calls as per the organization and ensure users are managed in the proper tenant / instance of WorkBoard. The IDP needs to be SCIM compatible and compliant.
Production base URL for WorkBoard’s SCIM API https://myworkboard.com/wb/apis/scim
Architecture: SCIM API Endpoints
This endpoint describes the operations supported by Service Provider.
ServiceProviderConfig (Context URI: /scim/ServiceProviderConfig)
{
"schemas" : [
"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"put" : {
"supported":true
},
"bulk":{
"supported":false
},
"filter":{
"supported":true
},
"changePassword" : {
"supported":false
},
"sort" : {
"supported":false
},
"etag" : {
"supported":false
},
"authenticationSchemes" : [
{
"name":"OAuth Bearer Token",
"description":"Authentication scheme using the OAuth Bearer Token Standard",
"specUri":"http://www.rfc-editor.organization/info/rfc6750",
"type":"oauthbearertoken",
"primary":true
}
],
"meta":{
"resourceType":"ServiceProviderConfig",
"location":"https://www.myworkboard.com/wb/apis/scim/ServiceProviderConfig"
}
}
Users (Context URI: /scim/Users)
Schemas (Context URI: /scim/Schemas) : This endpoint is not supported. This endpoint describes the schema and attributes definition for resources
Groups (Context URI: /scim/Groups) : This endpoint is not supported.
SCIM User
Schema
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:enterprise:1.0" ], "id": "internally_generated_user_id", "externalId": "id_generated_by_consumer_of_service", "userName": "email_address_generated_by_SP", "name": { "familyName": "Jensen", "givenName": "Barbara", "“middleName”": "“M.”" }, "displayName": "FULL_NAME", "emails": [ { "value": "example@example.com", "primary": true } ], "phoneNumbers": [{ "value": "555-555-5555" } ], "photos": [ { "value": "https://photos.example.com/profilephoto/72930000000Ccne/F", "type": "photo" } ], "timezone": "America/Los_Angeles", "active": true, "groups": [ { "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", "name": "Team 1" }, { "id": "fc348aa8-3835-40eb-a20b-c726e15c55b5", "name": "Team 2" }, { "id": "71ddacd2-a8e7-49b8-a5db-ae50d0a5bfd7", "name": "Team 3" } ] }
SCIM Token and Scopes
Workboard will create an administrative system user to pass SCIM API calls. This is to help ensure tracking purposes and control access to accommodate security requirements. SCIM tokens are different from OAuth or other access tokens provided by WorkBoard. You cannot access the WorkBoard Public API with a SCIM API token.
There is no scope associated with these tokens and the admin with the SCIM token and endpoint can perform the following user provisioning operations:
- [GET]: Get all the users of the organization for which the token is granted.
- [POST]: Create new users in the same organization
- [PUT]: Update existing users in the same organization, at this point, you can only update title and manager reporting relationship.
- [DELETE]: Disable users from the same organization.
Considerations
The minimum required attributes to provision a user are:
- firstName,
- lastName,
- userEmail
Additionally, we strongly recommend:
- title,
- managerEmailAddress
The manager’s email is what we use to create the individual reporting structure in WorkBoard.
When configuring managerEmailAddress, please ensure that you are using the correct namespace as identified above.
We provide the following as a custom attribute to help make it easier to pass manager’s email into WorkBoard.
Custom attributes
We also support using the custom attribute managerEmailAddress.
Namespace: urn:ietf:params:scim:schemas:core:2.0:User
This needs to be set to the user’s manager email address.
To set the reporting interval during the user's create request [POST], you can pass the manager info in following SCIM parameters or create a custom field to pass the manager information.
[ urn:ietf:params:scim:schemas:extension:enterprise:2.0:User ] => Array
(
[manager] => Array
(
[value] => managerIDemail@ domain .com
[displayName] => manageremail@ domain .com
)
)
or
[ urn:ietf:params:scim:schemas:extension:enterprise:2.0:User ] => Array
(
[manager] => Array
(
[managerEmailAddress] => managerIDemail@domain.com
)
)
or
[ urn:ietf:params:scim:schemas:extension:enterprise:2.0:User ] => Array
(
[manager] => Array
(
[managerId] => "Manager's WorkBoard user id"
)
)
Create a custom field
You can also create a custom field `managerEmailAddress`
namespace: urn:ietf:params:scim:schemas:core:2.0:User
Pass the manager email address during the user's create request and it will set the reporting.