IAM (OAuth)

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.

TODO (lance) enable HTTP once proper unmarshalling from x-www-form-urlencoded can be supported option(google.api.http) = { post: "/v2/oauth/token" };

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

TODO (lance) enable HTTP once proper unmarshalling from x-www-form-urlencoded can be supported option(google.api.http) = { post: "/v2/oauth/device/code" };

DeviceCodeRequest

Request for devices codes.

Name	Number	Description

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.	–

Error

OAuth2 error codes

Name	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

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.	–

GrantType

OAuth2 grant types that are currently supported.

Name	Number	Description
UNSPECIFIED	0
REFRESH_TOKEN	1
DEVICE_CODE_URN	2
CLIENT_CREDENTIALS	3
TOKEN_EXCHANGE	4

TokenType

Name	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