IAM (OAuth)

IAM APIs for authentication.

OAuth

Token

rpc Token (tetrateio.api.iam.v2.GrantRequest) returns (tetrateio.api.iam.v2.GrantResponse)

Grants tokens for a given grant type.

This is used by clients to obtain an access token by presenting required parameters for the requested grant type. Current only “urn:ietf:params:oauth:grant-type:device_code” is supported. When an error occurs, this will return a 4xx status code with an Error and ErrorMessage in the response.

DeviceCode

rpc DeviceCode (tetrateio.api.iam.v2.DeviceCodeRequest) returns (tetrateio.api.iam.v2.DeviceCodeResponse)

Requests device codes that can be used with a token grant with grant type “urn:ietf:params:oauth:grant-type:device_code”. For additional information please refer to the Device Authorization Grant RFC https://datatracker.ietf.org/doc/html/rfc8628

DeviceCodeResponse

Response with device codes for use with the Device Authorization flow. For additional information on the response parameters please refer to the Device Authorization Response section of the RFC https://datatracker.ietf.org/doc/html/rfc8628#section-3.2

Field Description Validation Rule

deviceCode

string
Code that the device uses to poll for tokens

userCode

string
Code the user enters in the verification URI

verificationUri

string
URI where to enter the user code

interval

int32
Rate in which to poll the token endpoint with the device code

expiresIn

int32
Expiration time of the device code in seconds

error

tetrateio.api.iam.v2.Error
Optional error code presented when an error or validation check failed.

errorMessage

string
Optional error message that contains more details about the error that occurred.

GrantRequest

Token grant request.

Field Description Validation Rule

grantType

tetrateio.api.iam.v2.GrantType
REQUIRED
Token grant type as specified in the OAuth2 specification. Current supported grant types are “urn:ietf:params:oauth:grant-type:device_code” and “refresh_token”

enum = {
  defined_only: true
}

deviceCode

string
OPTIONAL
Device code issued by the device authorization code endpoint when device code grant is used. This field is required when using a device_code grant.

refreshToken

string
OPTIONAL
Refresh token issued from a previous grant request. This field is required when using a refresh_token grant.

scope

List of string
OPTIONAL
List of requested scopes. This is a list that can include any of the scopes that are allowed by the client configuration. For refresh_token grants, this list may not include any scopes that were not part of the original token request.

clientId

string
OPTIONAL
Client ID for which the token grant request is being made. This is optional and when absent, TSB will use an appropriate client ID from configuration for the grant type being request. For a refresh grant type, this parameter may be required to ensure the appropriate client configuration is used.

resource

string
OPTIONAL
A URI that indicates the target service or resource where the client intends to use the requested token. This is used with the token exchange grant and should be the URI of TSB.

subjectToken

string
OPTIONAL
A token that represents the identity of the party on behalf of whom the request is being made. This is used with the token exchange grant and should be either an ID Token or Access Token from the configured offline token grant client.

subjectTokenType

tetrateio.api.iam.v2.TokenType
OPTIONAL
An identifier that indicates the type of the security token in the “subject_token” parameter. This is used with the token exchange grant.

GrantResponse

Token grant response.

Field Description Validation Rule

accessToken

string
Access token issued by the authorization server.

tokenType

string
Access token type such as “bearer” or “mac”.

expiresIn

int32
Expiration time of the access token in seconds.

refreshToken

string
Optional refresh token issued when the authorization server and client are configured to use refresh tokens.

clientId

string
Optional client ID used during the grant process. When present the client ID for subsequent refresh grant calls. While not a standard field on an OAuth grant response, this helps remove ambiguity when multiple OIDC configurations are present in TSB.

error

tetrateio.api.iam.v2.Error
Optional error code presented when an error or validation check failed.

errorMessage

string
Optional error message that contains more details about the error that occurred.

Error

OAuth2 error codes

Field Number Description

NO_ERROR

0

INVALID_REQUEST

1

INVALID_CLIENT

2

INVALID_GRANT

3

UNAUTHORIZED_CLIENT

4

UNSUPPORTED_GRANT_TYPE

5

AUTHORIZATION_PENDING

6

SLOW_DOWN

7

ACCESS_DENIED

8

EXPIRED_TOKEN

9

SERVER_ERROR

10

GrantType

OAuth2 grant types that are currently supported.

Field Number Description

UNSPECIFIED

0

REFRESH_TOKEN

1

DEVICE_CODE_URN

2

CLIENT_CREDENTIALS

3

TOKEN_EXCHANGE

4

TokenType

Field Number Description

TOKEN_TYPE_UNSPECIFIED

0

TOKEN_TYPE_ACCESS_TOKEN

1

TOKEN_TYPE_REFRESH_TOKEN

2

TOKEN_TYPE_ID_TOKEN

3

TOKEN_TYPE_JWT

4