Appearance

Gateway ​

To simplify interaction with your backend, the platform features an API gateway. The framework includes a utility function that can direct requests towards this gateway, but only if the request URL matches with an endpoint in your app's manifest file.

createRequest() ​

Use the createRequest() function to create a native Request.

The function signature is the same as when creating a new Request() with the exception that we do not support passing a Request as the first argument.

Optional: to configure a proxy for the request, use the AllianceRequestHeaders.TargetProxy header, the gateway will configure the underlying request library to use the proxy configuration defined as https://user:password@proxy.server.net:9000.

ts
import { AllianceRequestHeaders, createRequest } from '@telia-ace/alliance-framework';

const request = createRequest('https://my.backend.net', {
    method: 'POST',
    body: JSON.stringify({
        foo: 'bar',
    }),
    headers: {
        [AllianceRequestHeaders.TargetProxy]: env.PROXY_URL,
    },
});
const result = await fetch(request).then((result) => result.json());

Alliance JWT ​

The API gateway will transmit a JWT (JSON Web Token) as a bearer token within the authorization header.

Once this token is decoded and validated, it will provide at least the following pieces of information.

PropertyTypeDescription
issstringJWT issuer.
audstringApp name.
substringUser object ID
namestringUser display name.
https://alliance.teliacompany.net/user_type'user' | 'system-admin'User type.
https://alliance.teliacompany.net/user_emailstringUser email.
https://alliance.teliacompany.net/user_privilegesstring[]App permissions assigned to the user. Limited to the permissions for the app making the request.
https://alliance.teliacompany.net/workspacestringCurrent workspace URL friendly slug.
https://alliance.teliacompany.net/workspace_namestringCurrent workspace display name.

Example

json
{
    "iss": "Alliance",
    "aud": "the-amazing-app",
    "name": "John Doe",
    "sub": "00000000-0000-0000-0000-000000000000",
    "https://alliance.teliacompany.net/user_type": "user",
    "https://alliance.teliacompany.net/user_email": "john.doe@email.com",
    "https://alliance.teliacompany.net/user_privileges": ["read:stuff", "write:stuff"],
    "https://alliance.teliacompany.net/workspace": "demo-workspace",
    "https://alliance.teliacompany.net/workspace_name": "Demo Workspace"
}

Public keys ​

To ensure the authenticity of the JWT, the API gateway supplies public keys that your backend can use for verification.

The public keys are supplied through three distinct endpoints, each presenting the keys in a unique format - one in PKCS (Public-Key Cryptography Standards), the other in SPKI (Subject Public Key Info) and the last as a CSP blob (required by legacy .NET framework backends). To accommodate our ability to alter our private key dynamically, we suggest that you use the gateway endpoints to fetch the public key in real-time whenever you're validating the Alliance JWT. This ensures that you always have the most current key for verification.

They keys are available on: <environment>/-/gateway/public-key/(pkcs|spki|csp)

You can pass the ?plain query string, if you need the key without -----BEGIN PUBLIC KEY------prefix and -----END PUBLIC KEY------suffix.

Local development ​

WARNING

The port may vary if you've set a different port specifically for the gateway in your configuration.

Production ​

Test ​