Introduction
- SCIM stands for “System for Cross-domain Identity Management”
- Can be used to Create, Read, Update and Delete (CRUD) locker users and user groups within Releezme through a REST
- The API is based on the following RFC’s:
Definitions
- Locker user: a user who interacts with via badge, Releezme app, or API integration for their They do not have a username/password to login to the Releezme portal.
- System user: a user who has a username/password to login to the Releezme portal. Note: the Releezme portal can also use customer SSO for
- API system user: a “service” user who has a username/password to login to the System API or SCIM API via the identity
- Note: System and API system users are initially created by Locker users can be created by the customer via configuration website, import or SCIM API.
Basics
- The SCIM API is a REST based API, which means that is uses standard HTTP operations such as GET, PUT, POST and
- With these operations it is possible to do create, read, update and delete (CRUD) of
- The resource supported by Releezme are:
- User, which represents the locker user in
- Group, which represents the user group in
- Examples:
- GET /api/users which retrieves retrieve all users.
- POST /api/users with a JSON content will create a new
- GET /api/groups/42d7cfdf-73a0-45e0-b796-234a88625f87 which retrieves a specific
User Entity Example
User resource attributes
- Releezme supports a subset of SCIM attributes:
- Username: customer supplied unique
- Name: given name and family
- Active
- Emails: only 1 email address is
- Groups: zero or more groups can be set on the
- Releezme adds a custom attribute for badges, which only has a value and display
Id/username
- “id” property in a user entity is filled by Releezme with a unique
- “username” property in a user entity is given to Releezme by the client and must be a unique
Id/username approaches
- SCIM only allows PUT/DELETE/PATCH calls by using the “id” property and not the username. So there are two approaches for this:
- Client ensures that they also know the “id” of the users within Releezme, by storing it locally when creating users or by retrieving the users in bulk.
- Client retrieves the user from Releezme by using the GET /users call with a username This will return the single user entity if it exists in Releezme.
Domain Model
- A company consists of one or more locations and each location has one or more sections. And finally each section contains locker banks with one or more
- A locker user is part of zero or more user
- Access for users to (specific lockers) is controlled by a link between a specific user group and a locker
User groups
- A user should normally be put into a user group, since without it, the user has no rights to a
- Configuring user groups is not trivial, therefore Releezme does not allow creation, deletion or modifications to user groups via the
- When retrieving user groups, the list of users in the group is never returned.
Supported Operations – Discovery
- SCIM defines several end-points which are used for discovery of features and data
- Service provider configuration: documents the features supported by a
- Schemas: documents the schemas used for user and group
- Resource Types: documents the resource types supported by the
Supported Operations – Resources
- User resources:
- GET: retrieve a single user or all users (paged)
- DELETE: delete a single
- POST: Add a new user
- PUT: Update an existing user
- PATCH: Update one or more attributes from a user by using a sequence of add, remove or replace values.
- Group resources:
- GET: retrieve a single group or all groups (paged)
- Note that Groups cannot be created, updated or
Swagger Support
- Integration API Server supports swagger:
- Swagger Support https://acc-scim.releezme.net/swagger
- Use https://editor.swagger.io/ to check the swagger and generate
- Or use https://github.com/swagger-api/swagger-codegen for command- line code
Locker User Transfer
Locker User Transfer (2)
- Customer server logs in to the Releezme Identity Server through OAuth 0 with a client specific client id/secret, and a company specific API system user with a username/password.
- Note: one client server can access multiple company through additional company specific API system
- Customer server communicates with customer specific locker user data source
- Customer server synchronizes locker users with Releezme:
- Create new locker users in Releezme when create in their
- Read locker user users in Releezme and check if they in their source. (note: possible action could be to delete “unknown” Releezme locker users, or just some other action).
- Update locker users in Releezme when changed in their
- Delete locker users in Releezme when no longer present in their
Authentication
- Authentication of the caller of the System API is handled via OAuth 2.0 with a resource owner password See RZM_191.
- Flow uses a password grant and a refresh
- A client id and secret identify the client server as a
- An API specific system user identifies the company to which the client has access
- Note that some third-party servers handle multiple companies in Releezme while using the same client id and
Authentication – Flow
Authentication – Flow (2)
- Client logs into the identity server with username/password.
- Identity Server returns access token and refresh token
- Client uses access token to communicate with the System API/SCIM API server. After 1 hour, the access token expires and API’s return
- Client users refresh token to get a new access token and refresh
- Client uses access token to communicate with the System API/SCIM API server. After 1 hour, the access token expires and API’s return 401.
- After 30 days the refresh token expires and cannot be used anymore on the identity The client must then login with username/password again.
Document References
- RZM_161: SCIM Integration Manual
- RZM_191: Identity Server Interface Requirements Specification
- SCIM Core Schema: https://tools.ietf.org/html/rfc7643
- SCIM Protocols: https://tools.ietf.org/html/rfc7644
Next Steps
- Customer should supply the following:
- Email address of the SCIM API system user. Normally this should be a service account. An email will be send there to setup the password. Note: this user does not have access to the
- Mobile phone number to send the client secret
- Additional email addresses for system users with access to the Releezme website. Each user will get a signup
- Vecos will then:
- Create integration company in Releezme’s integration
- Create the SCIM API system user
- Create the client id and secret. Id is sent via email. Secret via text
Finalizing the integration
- During integration, support will be given by the Vecos integration engineer if
- Once the customer is finished with it’s implementation, then:
- Do a realistic test run of you
- Send the timestamps (UTC) of the test run and a summary of the actions to the integration
- After previous step, the integration engineer verifies the results and checks if everything is correct.
- If so, then access to production is granted (note that everything must check out contractually also).
- If not, then feedback is given and