Intro to Service Accounts and Connected Apps

A service account, sometimes referred to as a system account or machine user, is a non-human privileged account that is created explicitly to provide a security context for services, typically APIs. These accounts' authentication needs are different from those of human users of the Tendo platorm. Instead of using a username and password like human user accounts do, service accounts use secret keys and generated tokens for authentication.

Also unlike human users, service accounts don’t need a person record. Service accounts include:

• Name
• Email - Used for contacting the service accounts' owner and username
• Phone - Used for contacting the owner

Like human users, one or more roles can be associated with a service account to restrict its access to Tendo’s system, and service account users can be activated or deactivated.

Service Accounts are maintained separately from human users.

Examples of service accounts that Tendo uses:

• Iris may be set up to service many users or set up by an admin to run behind the scenes to take care of an internal system process.
• MDsave wants to access objects data through Tendo’s APIs.
• A background process may be set up to do periodic data processing for which a service account could be the user of record.

Along with service accounts, internal users such as engineering and QA need generated tokens for use with APIs. This issue typically comes up with Postman. This requires providing an OAuth 2.0 route for connecting Postman or another application. Tendo provides a OAuth 2.0 standards-based process by which an external app can connect to Tendo and access Tendo’s APIs. This includes:

• Configured Connected Apps
• Generating Client IDs and Client Secrets for a Connected App
• Service Accounts (non-human users) that are defined in the Access section of Tools with assignable Roles.
• Service end points to support a OAuth 2.0 flow.

This enables integrations to be configured with the Tendo API with Service Accounts and Tendo employees to configure Postman with Tendo.

OAuth 2.0 Process Flow

Tendo supports a basic OAuth 2.0 client credentials grant type.

Step 1 - A connected app submits a user request to the authorization server.

In a user interaction with the client app, an authorization link to the Tendo authorization server is used to begin the access process. The link looks like this:

https://www.tendo.com/v1/oauth/authorize?response_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Link parameters include:

• client_id - This is the application’s client ID (how the API identifies the application). See below for the connected app setup.
• client_secret - The application’s client secret (how the API verifies the identity in authorization). See below for connected spp setup.
• Response_type=client_credentials - Specifies that the application is requesting an client credentials grant

Step 2 - The Tendo authorization server verifies the request and grants the access token.

The service call uses the client_id and client_secret to verify the identity of the connected app. The service account associated with the connected app is used as the user with the connection. The service account roles are used to limit access just like human user roles.

Once authorization is complete, the service returns an access token for subsequent access of resources.

Step 6 - The client app uses the access token.

The application is now authorized. It may use the token to access the user’s account via the service API for the resource service, limited to the scope of access, until the token expires or is revoked. If a refresh token was issued, it may be used to request new access tokens if the original token has expired.

Step 7 - The resource server returns resources

With a valid token used in the service API call, the resource server returns the requested resources, completing the flow.

A connected app must be defined in Tendo in order to secure the access point. The connected app definition should include:

• Name
• Active checkbox
• Type (Client or Service)
• Protocol (OAuth 2.0)
• Grant Type (Client Credentials) - Grant type is specific to OAuth 2.0 Protocold

To access Service Accounts and Connected Apps, navigate in Atrium to Tools, and click Access on the main left navigation bar. At the top of the page are three tabs, Roles, Service Accounts, and Connected Apps.