Clients

Integrations > Security > OAuth > Clients

The Clients screen lists and configures all OAuth clients that may connect to an instance of Medallia Experience Cloud. OAuth clients are applications that request or use resources served from Medallia Experience Cloud. A client is typically a single application or service, such as mobile application like Medallia Mobile or external service that requests data from Experience Cloud.

There are several OAuth authorization-schemes available for providing the authorization, and different types of clients require different authorization configurations. While some global settings are defined on the Configuration screen, each type of scheme has specific settings that are unique to the client, and in some cases override the global settings. 

The Clients screen lists each client. Names that end with "(Internal)" are used by Medallia Experience Cloud and should not be changed or deleted without first consulting with Medallia. 

Warning: Do not create or delete clients, and with the exception of where noted in this document, do not change setting without first consulting with Medallia. You may safely change

  • Timeouts to override the global settings

  • Refresh token, expire after idle, and IP allow-list properties

  • Client secret (for applications using the APIs.

Click on a name in the list to view or edit the client.

Properties

Client ID
(Do not change) Unique name of the client. This is the client_id parameter applications pass this to OAuth server.
Description
Text description of the client. Use this to record notes about the client, such as, what the client was created for, who the contact is for the client, and when it was created.
Active
When active, the client is processing authentication requests. A client may become inactive after a number of failed authentication attempts, as defined by the Invalid client authn tries option.
Platform OAuth Subject
Checking this enables this client to be a subject for platform OAuth client assertions.
Client secret status
Whether or not a client secret has already been generated for this client.
Generate new client secret
Clicking this option generates a new client secret for this client. After clicking (and confirming) this option, the new client secret is reported at the bottom of the page. This is the only time the client secret will be shown, so make a note of it.
Invalid client authn tries
Reports the count of times authorization attempts have failed for this client. This option is only available for Confidential clients.
Max client authn tries
Max count of tries allowed before the client is blocked (made inactive). Enter zero (0) to disable this feature. This option is only available for Confidential clients.
Confidential
(Do not change) Indicates the client is capable of keeping the Client Secret secure, such as when the client is a back-end server with restricted access. This must be on for Client Credential grant-types.
Issue Refresh Token
The client may request a refresh token. Generally this is turned on. Some configurations turn this off when the Authorization code lifetime timeout setting is sufficiently long enough to accomplish the task in the request, such as a single API request or update.
Note: Applications that use refresh tokens must store them securely.
Expire refresh token after an idle timeout
Automatically revoke access (sign-out) the client when the client is idle or inactive for a period of time defined by the Refresh token idle timeout property. See User sessions for a discussion about sessions and automatically expireing them.
Issue OpenID Token
(Do not change) Allows the client to request an OpenID ID Connect token (for authorization) by including the openid parameter in the list of requested scopes. This is primarily for communication between secure, internal services.
Enforce IP allow-listing on access token refresh
Client must use an allow-listed IP address when requesting the access token. See Allow OAuth clients for detailed information.
Grants
(Do not change) The type authorization method to use. Grant-types are:
Authorization code Grant (for WebApp and Mobile clients)
The authorization code is obtained an authorization server. Instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server (the the Redirect URIs for client property), which in turn directs the resource owner back to the client with the authorization code. Before directing the resource owner back to the client with the authorization code, the authorization server authenticates the resource owner and obtains authorization. Because the resource owner only authenticates with the authorization server, the resource owner's credentials are never shared with the client.
Client Credentials Grant (for backend services)
The client is associated with one of the AppID Accounts: everything the account has permission to access is also available to the client. When using this grant-type, the Client subject property identifies the account.
Restriction: When using this grant type, turn on Confidential or the authorization will fail.
Note: This grant-type is for accounts with secret codes, as opposed to Resource Owner grants which are accounts with sign-in privileges.
Implicit Grant (for JavaScript clients)
The client is an internal JavaScript application that directly retrieves the access token. It cannot be trusted with a client secret, and it does not get an refresh token. The app and server use the Redirect URIs for client property to pass the token.
Restriction: This grant-type is not supported at this time.
JWT Bearer Grant (for clients that have tokens from another IdP)
Must also define the JWT Bearer Grant properties.
Restriction: This grant-type is for internal-use only.
Resource Owner Grant (for simple user/pw clients)
The client is associated with a Users account: everything the account has permission to access is also available to the client. When using this grant-type, the Client subject property identifies the account.
Restriction: Thiis grant-type is not supported at this time.
Token Exchange Grant (for certain Multi-tenant clients)
Internal use only.
Redirect URIs for client
(Do not change) The URI where the authorization code is sent for redirection based grants: Authorization code for Grant and Implicit Grant.
Client subject
(Do not change) The AppID Accounts to use when Grant is either Client Credentials Grant or Resource Owner Grant. The client will assume this AppID's access permissions to Medallia Experience Cloud.
Post logout redirect uris
Redirect the user to this URI after signing-out.

Consent forms ask user-clients to agree to trust the application to connect to Medallia Experience Cloud. The user must consent or the application will not be allowed to connect to the servers.

Important: It is the application's responsibility to obtain consent. Use this option only when absolutely necessary, such as when local laws require it. Generally, applications that have the necessary credentials to authorize with the OAuth server are assumed to be trusted by the administration that set up the client.

When using a consent forms, users see a dialog the first time they connect to Medallia Experience Cloud. The dialog includes options to agree or disagree to connect, and it optionally includes the following information:

  • A name or title for the consent form

  • A description asking for consent

  • A link to a web page for more information

  • An image (usually the company logo), retrieved from a URI

Ask end user for consent
Whether or not to prompt client/users to consent to connecting to Medallia Experience Cloud.
Name
Name or title to include in the consent form.
Description
Text to include in the dialog asking users them to consent to using OAuth.
Web URI
URI to include in the consent dialog. This should link to a company web page, possibly one that provides detailed information about the necessity for consenting to use OAuth.
Logo
URI to an image to include in the consent dialog.

Token Timeout Overrides

Timeout properties determine how long and how often clients have access to a server's resources. The timeouts are defined globally for the instance on the Configuration screen screen. Use the properties on this screen to override the global values specifically for this client.

Important: For a detailed discussion of these properties, and for example scenarios of different configurations, see Configure OAuth timeouts.

Initially these properties are read-only showing the global settings. To make these properties editable (to override the global settings):

  1. Turn on the Override default token timeouts property

  2. Click Save.

    The override properties are now editable.

Access token lifetime (seconds)
Access tokens grant access to resources for a short period of time. After the expire, the application may request new tokens.
Refresh token lifetime (hours)
Refresh tokens authorize clients to request access tokens for a period of time. After they expire, clients must re-authenticate (such as re-sign in) to acquire a new refresh token.
Refresh token idle timeout (seconds)
Refresh idle is how long the token may be idle (unused) before forcing the client to re-authorize (re-sign-in).
Authorization code lifetime (seconds):
(read-only) Authorization codes are one-time use-codes used during authorization. The OAuth server issues the code to the client, and the client must immediately return it to the OAuth server when requesting the first access token.

JWT Bearer Grant configuration

JSON Web Token (JWT) is an open standard for securely transmitting information in a JSON object. The information is digitally signed using a public/private key pair using the RSA or ECDSA standard.

Restriction: The functionality is currently for internal-use only.
Important: Applications that communicate with Medallia Experience Cloud APIs must include a JSON Web Token with the payload.
Restriction: JWT tokens must be secured with RSA 2048 bits, or with Elliptic Curve P256, P384, or P513 algorithms. HMAC signatures are not supported.

For a discussion about how public and private keys work, see SSH key pairs.

Key rotation

The OAuth server supports key rotation to allow the periodic changing of the public key used to sign JWT tokens. However, to avoid interruption of access, the server recognizes both the new and old keys. Each key has a unique Key ID that identifies it. Applications include the ID in the kid header parameter of the JWT token to indicate which key was used to sign the token. The server then uses the ID to know when key was used for decrypting the token.

To rotate keys:

  1. Copy the Key ID value to the Key ID Old parameter.

  2. Copy the Public Key value to the Public Key Old parameter.

  3. Enter a new Public Key value.

  4. Enter a new Key ID value.

  5. Click Save to apply the settings to the server.

  6. Notify all clients to start using the new key and key ID.

Issuer
The issuer for the JWT tokens
Audience
Audience claim for incoming JWT tokens. All incoming JWT tokens must have an aud header parameter and it must be set to this value.
Key ID
A unique string associated with the Public Key for the purpose of identifying the key when using key-rotation (see above). This is the value the application must include in the kid header parameter of the JWT token to indicate the public key that signed the token.
Tip: This value is required when using key-rotation, but optional otherwise. However, it is good practice to use the Key ID in the event you later chose to use key-rotation.
Public Key (RSA or EC)
Public key for signing JWT tokens. Must be RSA 2048 bits, or Elliptic Curve P256, P384, or P513 algorithms. HMAC signatures are not supported.
Key Alg
(read-only) algorithm used to create the Public Key.
KeyId Old
Key ID associated with the Public Key Old key when using key-rotation (see above).
Public Key Old (RSA or EC)
Previous Public Key value when using key-rotation (see above).
JWKS URI for client's public keys
URI for locating the Key ID and Public Key. When specified, the keys provided in the URI are used instead of the Key Id and Public Key properties (if they are also specified).
Disable TLS validation and Hostname verification on JWKS URI access
Disable transport layer security (TLS) validation and hostname verification during the SSL handshake step when accessing the JWKS URI. Only do this during for development and quality assurance (QA) clients. For security, never disable this for production clients.
Current JWKS keys
(read-only) List of the active JWKS keys.