SymetryML REST API Security

SymetryML REST Request Authentication

The SymetryML REST API allows you to authenticate your requests. The API’s authentication is based on a "message-authentication code" signature created using specific parts of the REST API HTTP request.

Message authentication code (MAC) provides a way to verify the integrity of information sent in a REST request based on a secret key known only to the request sender and receiver. Because only two parties know the secret key, validating the MAC signature also authenticates the corresponding REST request. For this reason, each SymetryML API account has a secret key associated with its SymetryML key ID that is used to create a MAC signature for each REST request. The SymetryML server uses this secret key to verify signatures and authenticate all requests.

Authentication Header

The SymetryML REST API uses the HTTP Authorization header to pass authentication information to the server. The header contains the information in the following table.

The most common MAC algorithms are Hash-based Message Authentication Code-Message Data 5 (HMAC-MD5) and HMAC-SHA2. The algorithm used in the SymetryML REST API is HMAC-SHA2, as specified in RFC 4868.

SymetryML Date Header

Each SymetryML REST request must contain a SymetryML Date header. The content of this header is a date and time based on the Universal Coordinated Time/Greenwich Mean Time (UTC/GMT) time zone. This header is called sym-date.

The SymetryML Date header must:

• Follow this syntax:

yyyy-MM-dd HH:mm:ss;nanoseconds

For example:

2014-07-31 08:01:07;1245

• Before 5 minutes of the server time.
• Not be more than 1 minute ahead of the server time.

Authentication Errors

If an authentication error occurs, the server returns a 401 (UNAUTHORIZED) response. The response contains a stringToSign entity that describes the string that the server was trying to validate when the error occurred. You can use this string to troubleshoot the request and identify the validation issue.

Note

The server omits the secret key from the response and outputs SECRETKEY in stringToSign.

The following shows an example of an unauthorized response. .

{
      "statusCode":"UNAUTHORIZED",
      "statusString":"Invalid Signature",
      "values":{
            "stringToSign":"DELETE\\n\\nSECRETKEY\\n2013-05-22 18:13:38\\nc1\\nhttp://192.168.0.19:8080/symetry/rest/c1/sYMETRYMLs/r1\\n"
      }
}

Authentication Error Codes

To help you identify and resolve authentication issues quickly, the SymetryML REST API supports a variety of error codes. The following table describes the supported error codes.

Single Sign-On (SSO) Authentication

SymetryML supports Single Sign-On (SSO) authentication, allowing users to authenticate using enterprise identity providers instead of managing SymetryML-specific credentials. When SSO is enabled, users authenticate through their organization's identity provider and then obtain SymetryML credentials (customer ID and secret key) to use with the REST API.

Supported Authentication Protocols

SymetryML supports two SSO authentication protocols:

1. OIDC (OpenID Connect) - Works with identity providers such as:

   • Auth0
   • AWS Cognito
   • Okta
   • Any OpenID Connect compliant provider

2. LDAP (Lightweight Directory Access Protocol) - Works with directory services such as:

   • AWS Simple AD
   • Active Directory
   • OpenLDAP
   • Any LDAP v3 compliant directory

SSO Authentication Flow

When SSO is enabled, the authentication flow works as follows:

1. User authenticates through the identity provider (Auth0, AWS Cognito, LDAP, etc.)
2. After successful authentication, user calls the /smlaccess endpoint
3. SymetryML returns the user's customer ID and secret key
4. User uses these credentials to make authenticated REST API calls using the standard signature-based authentication

Get SML Credentials After SSO Login

After successfully authenticating through your SSO provider, use this endpoint to retrieve your SymetryML credentials.

URL

GET /smlaccess

Authentication

This endpoint requires that the user has successfully authenticated through the configured SSO provider. The authentication is handled by pac4j session management.

HTTP Responses

HTTP Response Entity

The response contains a JSON object with the following structure:

{
  "statusCode": "OK",
  "statusString": "OK",
  "values": {
    "smlCredentials": {
      "smlusername": "<customer-id>",
      "smlusersecretkey": "<secret-key>"
    }
  }
}

Sample Request/Response

Request:
GET https://your-server.com/smlaccess

Response:
{
  "statusCode": "OK",
  "statusString": "OK",
  "values": {
    "smlCredentials": {
      "smlusername": "john.doe",
      "smlusersecretkey": "aB3dE6fG9hI0jK1lM2nO3pQ4rS5tU6vW=="
    }
  }
}

Using SSO Credentials with the REST API

Once you have obtained your SymetryML credentials from the /smlaccess endpoint:

1. Use the smlusername as your customer ID ({cid}) in REST API URLs
2. Use the smlusersecretkey as your secret key for signing requests (see Authentication Header)
3. All subsequent REST API calls should use the standard signature-based authentication method

SSO Configuration

SSO must be enabled and configured by the SymetryML administrator. Configuration includes:

Enabling SSO

To enable SSO functionality, add the following JVM parameter to the JAVA_OPTS environment variable in your docker-compose.yml:

-Dsym.sso.enable=true

General Settings

All SSO configuration parameters listed below must be set in the SymetryML REST Configuration file (symetry-rest.txt). For more information about SymetryML REST configuration, see the Installation Guide - SymetryML REST Configuration.

OIDC-Specific Settings

For OpenID Connect providers (Auth0, AWS Cognito, etc.), add these parameters to symetry-rest.txt:

LDAP-Specific Settings

For LDAP providers (AWS Simple AD, Active Directory, etc.), add these parameters to symetry-rest.txt:

Example OIDC Configuration (Auth0)

In JAVA_OPTS, add:

-Dsym.sso.enable=true

In symetry-rest.txt, add:

rtlm.option.sso.authentication.protocol=OIDC
rtlm.option.sso.callback.handler.url=https://your-domain.com/sso/sso-callback-redirect.html
rtlm.option.sso.callback.finish.url=../../symetry-web/
rtlm.option.sso.logout.finish.url=https://your-domain.com/sso/sso-logged-out-redirect.html
rtlm.option.sso.create.sml.user.if.missing=1
rtlm.option.sso.oidc.client.id=YOUR_CLIENT_ID
rtlm.option.sso.oidc.client.secret=YOUR_CLIENT_SECRET
rtlm.option.sso.oidc.discovery.url=https://your-tenant.auth0.com/.well-known/openid-configuration
rtlm.option.sso.oidc.user.profile.name.attribute=email
rtlm.option.sso.oidc.user.profile.access.scopes=openid profile email

Example LDAP Configuration (AWS Simple AD)

In JAVA_OPTS, add:

-Dsym.sso.enable=true

In symetry-rest.txt, add:

rtlm.option.sso.authentication.protocol=LDAP
rtlm.option.sso.callback.handler.url=/symetry-web/sso-callback.html
rtlm.option.sso.callback.finish.url=../../symetry-web/
rtlm.option.sso.logout.finish.url=../../symetry-web/sso-logged-out.html
rtlm.option.sso.create.sml.user.if.missing=1
rtlm.option.sso.ldap.url=ldap://your-ad-server.example.com
rtlm.option.sso.ldap.search.dn.resolver.connection.bind.dn=cn=Administrator,cn=Users,dc=example,dc=com
rtlm.option.sso.ldap.search.dn.resolver.connection.bind.password=YOUR_PASSWORD
rtlm.option.sso.ldap.search.base.dn=cn=Users,dc=example,dc=com
rtlm.option.sso.ldap.search.filter=(cn={user})
rtlm.option.sso.ldap.user.profile.name.attribute=name
rtlm.option.sso.ldap.authentication.login.url=/symetry-web/sso-ldap-login.html

Auto-User Creation

When rtlm.option.sso.create.sml.user.if.missing is set to 1, SymetryML will automatically create a new user account and secret key when a user successfully authenticates through SSO but does not yet have a SymetryML account. This is useful for:

• Streamlining user onboarding
• Allowing any authenticated enterprise user to access SymetryML
• Reducing administrative overhead

When set to 0, only pre-existing SymetryML users can authenticate via SSO.

Security Considerations

• SSO credentials (secret keys) are generated automatically and should be treated with the same security as manually-created credentials
• The /smlaccess endpoint relies on session-based authentication managed by pac4j
• All subsequent REST API calls after obtaining credentials still require proper HMAC-SHA2 signature authentication
• Secret keys can be rotated using the standard SymetryML admin tools

APIs at-a-Glance

Please note that Every REST request that is made starts with the following canonical URL:

HTTPVERB /symetry/rest/{cid}

where:

• {cid} is the customer ID.
• HTTP VERB is a valid HTTP verb such as GET, PUT, POST, or DELETE.