Authentication

Most of the features in the SDK require the SDK to be authenticated with any type of authentication token. The SDK provides several mechanism to perform authentication. The SDK will cache the authentication information until they expire or new information will be provided by a re-authentication call.

Only re-authenticate the SDK, if you have not yet authenticated the SDK or if the current authentication information are not valid anymore. You don't need to re-authenticate the SDK after every initialization. If you want to check, if an authentication is required you can use the the modules get_current_authentication_method() method to verify, if the SDK is currently successfully authenticated with any known method. If the return value is None , you have not yet authenticated the SDK or the existing authentication information are not valid anymore. Too many re-authentications might result in API endpoints to rate limit the request.

OpenID Authentication

This is the preferred way of authentication. The SDK will receive an OpenID Access, Refresh and optionally ID Token. The SDK will internally handle the Access Token refresh logic if required.

It will also make sure, that no API calls will be performed, if it detects the credentials to not be valid anymore, e.g. the Refresh Token expired.

Swift

let credentials = AuthCredentials(
    accessToken: "OPENID ACCESS TOKEN", 
    refreshToken: "OPENID REFRESH TOKEN", 
    idToken: "OPENID ID TOKEN")
try kapeSdkManager.identity().openidAuthenticateWithAuthCredentials(
    authCredentials: credentials)

Kotlin

OpenID Username and Password Authentication

This method should only be used, if the regular OpenID Web Flow is not available. It only supports authentication with a username and password, while the regular OpenID Authentication might support a variaty of authentication methods. This internally uses the Resource-Owner-Password-Credentials Flow specifid in the OpenID standard.

Swift

try kapeSdkManager.identity().openidAuthenticateWithUsernamePassword(
    username: "jon.doe",
    password: "my_secret")

OpenID Authorization Code Authentication

This flow is requires, if an authorization code is already available, which usually is generated as part of the full OpenID Authentication flow. An example of this flow is the exchange of an XV Access Token for an OpenID Access Token. This is required to keep apps logged in, if they have a legacy XV Access Token stored and don't want to ask the user to provide username and password again.

Additionally, it can be used when opening "magic links" from a mail etc.

Swift

try kapeSdkManager.identity().openidAuthenticateWithAuthorizationCode(
    authorizationCode: "XYZ123",
 )

Opaque Token Authentication

In this mode, the SDK will not perform any authentication token validation and will just pass it to the endpoints which will then know how to validate it.

As the SDK internally manages authentication tokens per each user in a separate storage session, the app would need to provide a userId under which the SDK should internally store this token. This can also be any random string.

Swift

try kapeSDKManager.identity().authenticateWithOpaqueToken(
    userId: "user_1234", 
    token:"ANYTOKEN")

Legacy XV Authentication

This mode is used by legacy ExpressVPN apps and uses a JWT Access Token.

It's the responsibility to call this method whenever the current access token expired and a fresh one needs to provided.

Swift

let credentials = AuthCredentials(
  accessToken: "<ACCESS TOKEN>", 
  //not needed
  refreshToken:"", 
  //not needed
  idToken: "")
try kapeSDKManager.identity().authenticateWithXvLegacyAuthCredentials(
  authCredentials:credentials
)

Apple InApp Receipt Authentication

In this mode, you will provide an Apple InApp Receipt to authenticate the SDK using the Opaque Token Authentication method.