Authentication/Authorization
This section explains the different authentication flows supported by Envase Identity Manager. This is not a full guide about Authentication/Authorization, there is plenty of information out there, but it provides some recommendations depending on your application needs.
The Envase Identity Manager service is implemented as an extension on top of AWS Cognito, which means that the Authentication/Authorization flows supported are based on the support provided by that service. Envase does not provide any custom authentication/authorization flows, so if you are familiar with how AWS Cognito works, you should also be familiar with Envase Identity Manager.
Requesting Access for New Client
For each application or service that wants to integrate with other Envase applications and services, a new client needs to be registered. This registration happens “manually” as of the time of this writing, so you need to contact Envase Technologies to request the registration.
Depending on the status of your application, you will receive a client id and a client secret to one of our environments. Usually, we will give you access to the staging environment, so that you can try the different services away from production. Once your application is ready to ship, we will register a client for you in the production environment.
Before you request registration for a new client, you need to think about the type of application you will be developing. There are also differences in the type of authorization/authentication we allow related to whether you are an internal Envase application or service, as opposed to an external application or service integrating with Envase services.
External Applications and Services
External Web and Mobile applications are only allowed to access Envase services and applications on behalf of a user. This means that if you are implementing a Web or Mobile application, and you are not part of the Envase ecosystem of products, you need to request a client that will allow you to log in users.
There are two protocols supported to authenticate/authorize your client on behalf of the user. The first protocol, and the recommended one, is OAuth 2.0 using the Authorization Code flow. When you request to register a client that will use this flow, you will need to provide a redirect URL where the browser, or the app negotiation the flow, will be redirected to get the request token. You will want to insure that the redirect URL is part of your application or that your application can handle that redirect.
The following table shows the URL information you will need to authenticate using OAuth 2.0:
URL |
Value |
|---|---|
Authorization URL Staging |
|
Access Token URL Staging |
|
Authorization URL Prod |
|
Access Token URL Prod |
The second protocol you can use to authenticate/authorize your client is SRP (Secure Remote Password). This protocol allows you to safely provide your client id and secret, as well as, the user name and password required to log in a user. It is a straight forward protocol, and there are several libraries available that will do the work for you depending on the programing language that you use. You will need to insure that passwords for your users are kept safe, which is not an easy task; therefore, it is recommended that you use the OAuth 2.0 Authorization Code flow whenever possible.
You will need the AWS Cognito user pool id in order to use SRP, which will be provided when you register a client.
Internal Applications and Services
If you are implementing an application and service part of the Envase ecosystem, You have an additional authentication and authorization flow that you can use. For the most part, you will want to use the same flows described above in most cases. The exception is when you are implementing an application or service that need machine-to-machine access. In those case, you can use a client with Client Credentials. The URLs you need to be aware are the Access Token URLs provided on the table above.
There is an additional Development environment for internal use only that has its own URLs:
URL |
Value |
|---|---|
Authorization URL Dev |
|
Access Token URL Dev |
You can check Using Postman for more information about how to test the APIs you want to access using Postman. This is useful at the beginning to learn how to use the exposed APIs, as well as try new requests you will need to send from your application.
Access Tokens and API Keys
The different protocols described above provide an authorization token that applications and clients should use for subsequent requests. The authorization token is a JWT (JSON Web Token) that has multiple sections. You should extract the access token from the JWT and include it in the Authorization header of every request to an Envase service.
Some services will require an API Key with every request. API Keys are issued by Envase for specific reasons, and all the requests sent to Envase services must include that API Key when communicating with services that require them.
The API key should be included using the X-Api-Key header of the request for every call to a service that requires it. You can check the individual service documentation to know if an API Key is required.