Exchange Own Token

TerraCore v0

If your app uses own Auth backend, you can exchange it's token for Terra access_token following this guide.

General flow#

This flow requires several integration steps between your Auth backend and our system, please follow next section for details

Implementation steps#

Implement your Auth backend to generate the idToken#

Currently, we only support JWT-decodable token with following claims

Header#

Property	Description	Type	Constraint
`typ`	Only accept “JWT”	`string`
`alg`	Only accept “RS256”	`string`
`kid`	The kid for the public key used to sign this token	`string`	`required`

Example:

{
  "alg": "RS256",
  "kid": "0d57a0be-3ed2-42a2-b3e5-36ca7f932112",
  "typ": "JWT"
}

Payload#

Property	Description	Type	Constraint
`iss`	The Issuer Identifier for the Issuer of the response	`string`	`required`
`aud`	The audience that this token is intended for. If provider follows Auth2.0 and needs to verify claim aud, they need to register allowed list aud to IAM Service	`string`	`required`
`sub`	The identifier for the user	`string`	`required`
`iat`	The time the token was issued	`string`	`required`
`exp`	Expiration time on or after which the token must not be accepted. Represented in Unix time (integer seconds)	`string`	`required`
`name`	User profile name	`string`	`required`
`email`	User profile email	`optional`	`recommended`
`phone_number`	User profile phone number	`optional`	`recommended`

Example:

Given this context:

Company sample_company has an Auth backend (https://oauth.sample_company.com)
Company has 2 apps app_1 and app_2 that use this Auth backend
The idToken generated for app_1 will look like:

{
  "iss": "https://oauth.sample_company.com",
  "aud": "app_1",
  "iat": 1602472688,
  "exp": 1602476288,
  "sub": "38faff5b50794f389f5e53506ae1c97c",
  "name": "Sample User Name",
  "email": "sample_user@sample_company.com",
  "phone_number": "0987654321",
}

Implement your Auth backend to return public key#

This is the public key associated with the private key that you used to sign the above idToken, as an example the Google's api is https://www.googleapis.com/oauth2/v3/certs.
The api url is jwks_uri in next step.

Send us registration information so we can integrate your Auth backend#

Property	Description	Type	Constraint
`name`	Your Auth backend name	`string`	`required`
`provider`	Your Auth backend identifier (will be used in your client code for logging in later)	`string`	`required`
`issuer`	Authenticator issuer which is used when IAM verifies id_token for this issuer	`string`	`required`
`jwks_uri`	The API provider exposed jwks which contains public_key to verify JWT id_token (https://tools.ietf.org/html/rfc7517)	`string`	`required`
`client_id`	Allowed 3rd-party client	`string`	`required`

Example (using same above context)

{
    "name": "Sample Company",
    "provider": "sample_company",
    "issuer": "https://oauth.sample_company.com",
    "jwks_uri": "https://oauth.sample_company.com/.well-known/jwks.json",
    "client_id": "app_1"
}

Enable custom login method in Terra Console#

Please contact us we will setup it for you

Implement your client app to log in#

Installation#

Android
iOS
Flutter

implement("vn.teko.android.auth:terra-auth:$version")

Usage#

After user logged into your app and received the idToken from your Auth backend, use this code to log in

Android
iOS
Flutter

// create the credential
val credential = CustomTokenProvider.getLoginCredential(provider, idToken)
// login
TerraAuth.getInstance(terraApp).loginWithCredential(credential) { result: Result<Unit, Throwable> ->
  when (result) {
    is Result.Success -> // handle successful login
    is Result.Failure -> // handle failed login
  }
}

Where

idToken is the token that you received from your Auth backend after logging in successfully
provider is the value that you sent us at the step before.

final _terraAuth = await TerraAuth.getInstance(_appName);
final credential = CustomProvider.createCredential(idToken);
final result = await _terraAuth.loginWithCredential(credential);

showToast("Login Result: ${result.isSuccess}");

Where: idToken is the token that you received from your Auth backend after logging in successfully

Note To login with custom token credential, except idToken, you should config provider on Terra Console. Contact Terra team to get more information.