Mineral™ currently uses a proprietary solution to provide access to the Mineral™ platform application. This proprietary solution requires a shared key and a mapped user field to provide authentication and authorization for Mineral™ application resources.

Implementation Options:

• Client Site - Utilizes JavaScript to dynamically generate the Mineral™ application link.
• Server Side - Utilizes AES-256 CBC encryption to generate the token for the Mineral™ application link.

As the Mineral™ platform evolves, we will be deprecating our current application SSO offering in favor of OpenID Connect (OIDC), the timeline for this transition is under development.

Both Server-side and Client-side implementation samples are available here. If you need assistance or would like to see samples in another language, please let your account manager know or email us at Developer Support

Client applications may use OIDC to retrieve entities (e.g. company, user, issue, alert) via the Mineral™ Platform APIs or to provide seamless access to Mineral™'s web application. Note: entity and feature visibility are determined by Role-Based Access Control (RBAC) and may be modified only by changing a user's role assignment.

Implementation samples are available here. If you need assistance or would like to see samples in another language, please let your account manager know or email us at Developer Support

Sample API calls are also part of our Postman Collection

1. Client accesses the Mineral™ Identity Token API using their client credentials, a grantType of 'sso' and the mappedValue of the user they wish to sign-on as. (Samples showing this transaction are available both within the Postman Collection and the samples/oidc directory.)
2. Once the credentials and user information are validated an access token, refresh token, and sso_url will be returned.
3. The access token may now be submitted in the Authorization Header as a Bearer Token for all Mineral™ Platform APIs. Data requests are restricted based on the user's permissions and roles. The refresh token may be used to acquire a new access token once the current one has expired.
4. The sso_url may now be used to forward the user to our web application. Just redirect the user to the provided URI and they will be deposited into the Mineral™ web application.

1. Client application logs in to the IDP and receives and identity token and access token.
2. Client accesses the Mineral™ Identity Token API using their client credentials, a grantType of 'openid', the identity token and the access token.
3. Once the credentials and user information are validated an access token, refresh token and redirect URI will be returned.
4. The access token may now be submitted in the Authorization Header as a Bearer Token for all Mineral™ Platform APIs. Data requests are restricted based on the user's permissions and roles.

1. Client application logs in to the IDP and receives and identity token and access token.
2. Client accesses the Mineral™ Identity Token API using their client credentials, Mineral™ partner Id, a grantType of 'openid', the identity token and the access token.
3. Once the credentials and user information are validated an access token, refresh token and redirect URI will be returned.
4. The redirect URI may now be used in conjunction with the partner id and the desired destination URI (if any) to complete the transaction and deposit the user into the Mineral™ web application.

To get started with OIDC the following steps much be completed by the Client and their Mineral™ Account Team:

1. Client indicates which User field they will use for Single Sign-On (SSO) - email or username.

2. Mineral™ Production and Sandbox accounts are created and credentials (i.e. partner id, clientId & clientSecret) for each environment are provided to the client.

3. If an OIDC Identity Provider (IDP) is being used then the client must provide the following information to Mineral™ for each environment:

   a. Issuer (e.g. accounts.google.com)
   b. Identity Token Validation URL (e.g. https://www.googleapis.com/oauth2/v3/certs)
   c. User Information URL (e.g. https://www.googleapis.com/oauth2/v3/userinfo)
   

Mineral™ requires Clients to provide the following information to register a new IDP with the Mineral™ Platform:

1. An Application Registration Interface: An interface for client application (e.g. Mineral™) registration. Usually this results in generation of a unique pair of appId and appSecret. This interface is also used for other parameters like setting up a redirect URL.
2. Authorization Endpoint: An API that will accept a client authorization request and redirect to the IDP's login page.
3. Token Endpoint: An API provides a JWT based identity token and access token for the authenticated user.
4. Issuer: The JWT tokens contain attributes called claims. Issuer is one of the claims that helps the client application (e.g. Mineral™) in ensuring that token is coming from an authorized issuer.
5. Token Validation Endpoint: An API to validate signature of identity token using valid certificates.
6. User Info Endpoint: An API to retrieve authenticated user's details such as email, phone etc. This information is retrieved using the access token provided in step 3.
7. Documentation: Detailed IDP documentation on usage of all of the above points.

Once Mineral™ receives this information it will be added to the specified environment and validated. upon successful validation the Client will be notified that their IDP is now operational and available for use with that environment.