What is the Auth Service?
...
- /api/oauth/token - endpoint to generate an access token
- /api/oauth/check_token - endpoint to check an access token (Note: this endpoint is not included in the Auth Service API documentation.)
- /api/oauth/error - endpoint used to render errors from the authorization server.
- /api/oauth/confirm_access - endpoint used to render approval form in the authorization server.
- /api/oauth/authorize - GET endpoint is used to display user approval page or performs redirection if the user allowed it previously. POST is used to submit the authorization form and perform redirection to the client.
There are two three types of access tokens that can be generated by the Auth Service:
- User-based tokens - token is associated with a User, meaning a user account in the Reference Data service. The check_token endpoint returns a result with user info (username and Reference Data user UUID) with an USER authority. The USER authority currently has no meaning in the OpenLMIS system for access control. Access control is handled in role-based access control with Rights checks in the Reference Data Service. See the previous section for more info.
- Service-based tokens - token is not associated with any User, and is strictly for Service-to-Service communication. The check_token endpoint returns a trusted client result with a TRUSTED_CLIENT authority. Only Services should use these tokens because they essentially give "root" level access in the system. All endpoints in OpenLMIS services are accessible if they are accessed with a valid Service-Based Token. For more information about Service-based tokens, see the section below.
- API key - token works similar to the service-based tokens. It is not associated with any User, and it should be used for external partner to OpenLMIS communication. The check_token endpoint returns a trusted client result with a TRUSTED_CLIENT authority. Only trusted partners should use these tokens because they essentially give "root" level access in the system. All endpoints in OpenLMIS services that not require specific rights are accessible if they are accessed with a valid API key. Currently endpoints that require specific right are closed for API keys - but this will change in the near future. For more information about API keys, see the section below.
OAuth Client Credentials
Any service or app that accesses the Auth Service OAuth 2 endpoints is a Client in the OAuth 2 terminology. The OpenLMIS services and UI app each use credentials to connect to the Auth Service OAuth 2 endpoints. Each type of access token , User-based and Service-based, uses separate Client ID and Client credentials.
The Auth Service has a default client ID and secret for these two three Client IDs:
- User-based Client ID: user-client, secret: changeme. The UI app uses these credentials to log in and generate an access token on behalf of a user. Other browser apps, web apps or device apps that may allow users to log in to OpenLMIS would also use these User-Based Client credentials.
- Service-based Client ID: trusted-client, secret: secret. Only Services should use these credentials; for a Spring Boot application Service, these credentials are stored in the application.properties file.
- API Key Client ID starts with defined prefix (it can be changed in the application.properties file in the Auth service) and current date time in the following format: yyyyMMddHHmmssSSS, secret: is generated based on client ID.
Security Note: For security purposes, implementers must change the ID and secret of both clients when deploying an OpenLMIS implementation. It is also a good idea to change prefix for API keys. These credentials must be changed in the Auth service, in every other OpenLMIS service, and in the UI app.
...
In the OpenLMIS-UI, the client credentials are set within the config.json file and can be changed by replacing "authServerClientId" and "authServerClientSecret" keys.
In short, implementors must change these credentials in all services. Bootstrap and Demo data are public knowledge and should not be used in any production system.
...
- The endpoint can get the Authentication object from the application's security context.
- Check that the authentication isClientOnly() (meaning it does not have an OpenLMIS User behind it; true for service-based access tokens).
- Check that the client ID from the authentication is equal to service level token client ID (by defaults: trusted-client). If true, it can allow the request to continue.
- Otherwise, it would stop and return an Unauthorized HTTP code.
See the RightService.checkAdminRight() methods in the Reference Data Service for an example.
API Keys (aka Service Accounts)
The API Keys present a new way to communicate with OpenLMIS. It allows to communicate any external service with the OpenLMIS ecosystem. Each API key is always valid and never expired. Both Auth and Reference Data work together to handle API keys (aka Service Accounts)
...
. The Reference Data service maintains a list of service accounts and the Auth service maintains a list of client details (with client ID and secret) and related access tokens that are used as API keys.
The API Key is generated by the Reference Data Service. The Auth service takes part of this process but related auth's endpoint should not be used directly. Additional the endpoint accepts only service level token which should be from the Reference Data Service.
When is this used?
API keys should be used when external partners would like to communicate with OpenLMIS. In certain cases, an external partner may access to OpenLMIS endpoint using API key. For now each API key has a "root" access and only endpoints that does not require specific right are opened for API keys.
How can I create an API key?
An API key can be created only by an user. The endpoint in the Reference Data service do not allow to use service-level tokens or other API keys. To create the API key user needs the SERVICE_ACCOUNTS_MANAGE right. The following list presents typical workflow:
- User opens a browser to OpenLMIS.
- Browser loads the UI AngularJS application. The UI app starts running and it could present a login screen.
- User goes to the correct screen by selecting Service Accounts on the Administration dropdown.
- User clicks on Add button to generate a new API key. User does not provide any details.
User has ability to remove an API key by clicking Delete button next to the API key. This operation cannot be reverted and the API key is no longer valid.
How can my service accept API keys?
If you have an endpoint in a Java Sprint Boot application that needs to accept requests from external partners with API keys, here are the basic steps:
- The endpoint can get the Authentication object from the application's security context.
- Check that the authentication isClientOnly() (meaning it does not have an OpenLMIS User behind it; true for API Keys).
- Check that the client ID from the authentication has API key client ID prefix (by defaults: api-key-client-). If true, it can allow the request to continue.
- Otherwise, it would stop and return an Unauthorized HTTP code.
...