Credentials and Authentication

Index

• Overview
• Mechanism
  • CW_CREDENTIALS cookie
  • Scenarios
• CubeWerx Stratos Authentication Server
  • Deployment and configuration
  • Management of users and roles
  • Management of OAuth clients
  • Operations
  • Errors
• MaxSeats configuration
• HttpBasic-to-CwAuth bridge

Overview

CubeWerx web services can be configured (via the Dashboard, the admin web API or the Python API) to allow fine-grained access to operations and/or content to users based on the following types of credentials:

• IP address
• API key
• OpenID Connect
• Distributed Access Control System (DACS 1.2 and 1.4)
• CwAuth

Most of this documentation will focus on the latter type, CwAuth. CwAuth is a credentials mechanism developed by CubeWerx which has the following properties:

• It is secure. CwAuth credentials cannot be spoofed or manipulated. To accomplish this, a JWK public-key encryption mechanism is employed. Credentials can only be authenticated and served by a CubeWerx Stratos Authentication Server, and all servers involved can verify the authenticity of a set of credentials by successfully decrypting them with the public key of a known (and trusted) CubeWerx Stratos Authentication Server. Furthermore, as long as all connection endpoints are HTTPS, malicious third parties cannot gain access to credentials in transit.

• It is flexible. It is compatible with the various standard distributed-application architectures, including "thin" browser-based clients, hybrid server-side web applications, and "thick" desktop application. It does this by communicating the credentials via an HTTP cookie and documenting how servers and desktop applications should intercept, interpret and propagate this cookie. It is also adaptable to various backend authentication mechanisms. Furthermore, CwAuth credentials can be established via the HTTP Basic Authentication mechanism and through OAuth 2.0.

• It is role-based. In addition to indicating a username (i.e., a specific individual), a set of credentials can also indicate one or more project-defined roles. The access-control rules for a set of services can then be formulated based on these roles, providing a much more natural and flexible mechanism for access control.

• It is cascadable. In a service-chaining scenario (where, for example, a Web Map Server gets its data from a Web Feature Server), CwAuth credentials can be passed down from service to service (as long as they all have the same second-level domain name) so that all entities along the chain are aware of the user's credentials and can control access at each level accordingly.

• It is single sign-on. A user that has logged on to (i.e., received authenticated credentials from) a CubeWerx Stratos Authentication Server within a particular domain can then access any server within that domain without having to log in again.

• It is simple. By employing the standard HTTP cookie mechanism and standard public-key encryption technology, the CwAuth credentials mechanism is easy to understand, implement and configure. Unlike DACS, an Apache plugin is not necessary.

• It is efficient. In most situations, once the user has logged in, the various entities never need to contact the authentication server. Validation of credentials is achieved solely by successfully decrypting the credentials cookie with the authentication server's public key (which has been configured beforehand).

Mechanism

CW_CREDENTIALS cookie

CwAuth credentials are communicated via an HTTP cookie called CW_CREDENTIALS. Encoded within the value of this cookie is a small JSON document containing an authenticated set of credentials. These credentials are signed with the JWK private key (RFC 7517) of a CubeWerx Stratos Authentication Server that is set up to provide authentication for that domain. All other servers within the domain are equipped with the public key(s) of the trusted authentication server(s) of that domain. This allows the servers to verify the authenticity of the credentials, since a successful decryption with the public key of one of the trusted authentication servers implies that the credentials must have originated from that authentication server. Note, therefore, that it is not necessary for a server to contact a CubeWerx Stratos Authentication Server in order to decrypt or verify the authenticity of a set of credentials.

A user is authenticated by making a login request to a CubeWerx Stratos Authentication Server. This can be done directly by having the user visit the CubeWerx Stratos Authentication Server with his/her browser, at which point the user will be prompted for a username and password. The authentication server will then pass a CW_CREDENTIALS cookie containing the appropriate credentials back to the browser. Alternatively, a browser-based application can collect the user's username and password, and contact the authentication server on behalf of the user (via either an Ajax request or a redirection to the authentication server with a callback back to the application). Either way, the web browser receives a CW_CREDENTIALS cookie containing the user's authenticated credentials for that domain.

Since the CwAuth credentials for a particular domain are communicated via an HTTP cookie, web browsers (and thus browser-based applications) will automatically pass along such credentials when communicating with servers within that domain. Furthermore, properly-equipped servers can cascade such credentials to other servers further down the service chain by recognizing the CW_CREDENTIALS cookie in the request and passing it along in the HTTP headers of any requests that it makes.

A web service can determine the credentials of the current user in one of two ways:

1. by making a GetCredentials request to a CubeWerx Stratos Authentication Server and parsing the unencrypted credentials that are returned the response.

2. by decrypting the CW_CREDENTIALS cookie itself with the public key of a known (and trusted) CubeWerx Stratos Authentication Server, and zlib-decompressing (RFC 1950) the results.

A decrypted CW_CREDENTIALS cookie contains a JSON representation of the user's credentials, and has the following form:

  {
    "domain": "xyzcorp.com",
    "firstName": "John",
    "lastName": "Doe",
    "eMailAddress": "jdoe@xyzcorp.com",
    "authUsername": "jdoe",
    "authServer": "https://xyzcorp.com/cubewerx/auth",
    "roles": [ "User", "Administrator" ],
    "authTime": "2025-04-18T20:19:32.167Z",
    "expires": "2025-04-19T08:19:32.167Z",
    "loginId": "53vQyeTY",
    "hasMaxSeats": true
  }

All of the properties of this credentials object other than domain and username are optional. If the value of the hasMaxSeats property is false, it's usually omitted. The authServer property indicates the URL of the CubeWerx Stratos Authentication Server that authenticated the credentials.

Scenarios

Web-based application authenticating via Ajax request

1. The user clicks a "log in"/"sign in" button on the web-based application.

2. The web-based application prompts the user for a username and password.

3. The web-based application makes an Ajax "login" request to the configured CubeWerx Stratos Authentication Server, passing along the user's username and password.

4. The CubeWerx Stratos Authentication Server authenticates the user for the current domain and prepares a set of credentials which it encrypts using a private key and packages into a CW_CREDENTIALS cookie. This CW_CREDENTIALS cookie is then returned to the web-based application via the HTTP response headers. The HTTP response body contains an unencrypted version of the credentials in JSON format.

5. The web browser automatically absorbs the CW_CREDENTIALS cookie and will include it in all future HTTP requests to all servers in the domain that the credentials were authenticated for. The web-based application optionally parses the JSON response and greets the user.

Web-based application redirecting to authentication server

1. The user clicks a "log in"/"sign in" button on the web-based application.

2. The web-based application directs the web browser to the login page of the configured CubeWerx Stratos Authentication Server, including a callback URL (back to the appropriate state of the web-based application) as a parameter of the login page's URL.

3. The CubeWerx Stratos Authentication Server prompts the user for a username and password.

4. The CubeWerx Stratos Authentication Server authenticates the user for the current domain and prepares a set of credentials which it encrypts using a private key and packages into a CW_CREDENTIALS cookie.

5. The CubeWerx Stratos Authentication Server sends a web page back to the user displaying the authenticated credentials. The HTTP response headers of this web page include the CW_CREDENTIALS cookie, which the web browser automatically absorbs.

6. The CubeWerx Stratos Authentication Server directs the web browser back to the web-based application, which then greets the user.

Server cascading credentials to another server

1. A server receives a request that includes a CW_CREDENTIALS cookie in its HTTP headers.

2. The server optionally decrypts the CW_CREDENTIALS cookie with the public key of an authentication server. This step is only necessary if this server itself needs to control access based on user identity or if the authenticated user needs to be identified for some other reason (such as for logging or for a personalized greeting message).

3. When making a cascaded request to another server, the server checks the domain of the other server. If it's in the same second-level domain, it prepares a "Cookie" HTTP request header containing a copy of the CW_CREDENTIALS cookie, and passes that along with the cascaded request.

Desktop application authenticating via the HTTP Basic Authentication mechanism

1. The desktop application attempts to connect to CubeSERV via an "htcubeserv" URL, and is challenged for an HTTP-Basic identity.

2. The user supplies a username and password, and the desktop application attempts the connection to CubeSERV again. (Or the application supplies a configured or cached username and password on the first request.)

3. The CubeSERV authenticates the HTTP-Basic identity and prepares CwAuth credentials for the user by logging into the authentication server on the user's behalf.

4. The HTTP response includes a CW_CREDENTIALS cookie so that, if the application supports cookies, future requests can be made more efficiently.

In each of the above scenarios, rather than sending a CW_CREDENTIALS cookie to a CubeWerx server, the client can send a request header of the form "Authorization: CwAuth <authorizationToken>", with the authorization token returned in the response of the "login" request.

CubeWerx Stratos Authentication Server

Deployment and configuration

Deployment

The CubeWerx Stratos Authentication Server is typically deployed under the URL "<deploymentUrl>/auth" on one or more of the web servers in a particular domain. More than one authentication server can exist in a single domain, and they can be identical (i.e., use the same backend authentication database) or specialized. It is strongly recommended that all authentication servers be accessible only through HTTPS in order to avoid the possibility of authenticated credentials being sniffed in transit by a malicious third party.

Management of keys

A public-private key pair is automatically generated for each deployed CubeWerx Stratos Authentication Server. For a single CubeWerx Stratos deployment which uses its own authentication server, this is sufficient. However, if a single authentication server is to be used by more than one CubeWerx Stratos deployment in the same domain and/or multiple authentication servers are to be used by a single CubeWerx Stratos deployment in the same domain, then the public keys of each of the authentication servers must be distributed to each of the CubeWerx Stratos deployments. This is done by executing the following command on each of the CubeWerx Stratos deployments, for each of the remote authentication servers:

    cwauthadmin installKey <cwAuthServerUrl>

E.g.:

    cwauthadmin installKey https://auth.xyzcorp.com/cubewerx/auth

This will fetch the public key from the specified authentication server and install it so that this deployment will be able to recognize credentials that are generated by that authentication server.

At any time, you can get a list of which keys are installed for a particular CubeWerx Stratos deployment by typing:

    cwauthadmin listKeys

The local public-private keypair will be listed as "private", and the other entries (if any) will be the URLs of the remote authentication servers whose public keys have been installed.

Type cwauthadmin by itself for more information.

Configuration parameters

Several configuration parameters (with names of the form "auth.*") exist for configuring a CubeWerx Stratos Authentication Server. See their descriptions in the Configuration Editor for more information.

Management of users and roles

To list the users and/or roles of a CubeWerx Stratos Authentication Server, execute one of the following commands (in a command line shell on the authentication server itself):

    cwauthadmin listUsers
    cwauthadmin listUserDetails [<username>]
    cwauthadmin listRoles
    cwauthadmin listRoleDetails [<rolename>]

To add, edit or remove the users and/or roles, execute one of the following commands:

    cwauthadmin addUser  username=<username>
                         email=<emailAddress>
                         password=<password>
                         [realName=<firstName> [<lastName>]]
                         [firstName=<firstName>]
                         [lastName=<lastName>]
                         [maxSeats=<maxSeats>]
                         [roles=<roleName>,<roleName>,...]
                         [isEditable=true|false]
                         [isEnabled=true|false]

    cwauthadmin editUser username=<username>
                         [email=<emailAddress>]
                         [password=<password>]
                         [realName=<firstName> [<lastName>]]
                         [firstName=<firstName>]
                         [lastName=<lastName>]
                         [maxSeats=[<maxSeats>]]
                         [roles=<roleName>,<roleName>,...]
                         [addRoles=<roleName>,<roleName>,...]
                         [removeRoles=<roleName>,<roleName>,...]
                         [isEditable=true|false]
                         [isEnabled=true|false]

    cwauthadmin removeUser <username>

    cwauthadmin addRole  role=<roleName>
                         [description=<description>]
                         [contact=<emailAddress>]
                         [users=<username>,<username>,...]

    cwauthadmin editRole role=<roleName>
                         [newRoleName=<newRoleName>]
                         [description=<description>]
                         [contact=<emailAddress>]
                         [users=<username>,<username>,...]
                         [addUsers=<username>,<username>,...]
                         [removeUsers=<username>,<username>,...]

    cwauthadmin removeRole <roleName>

Alternatively, management of users and roles can be performed through the CubeWerx Stratos Authentication Server's editUserInfo operation (with Administrator privileges), the admin web API, the Python API or the Dashboard.

Management of OAuth clients

To manage the registration of OAuth 2.0 (RFC 6749) clients, execute one of the following commands:

    cwauthadmin listOAuthClients

    cwauthadmin addOAuthClient
                         title=<title>
                         clientType=public|confidential
                         clientSecret=<password>
                         [redirectUris=<redirectUri>,<redirectUri>,...]
                         [contactName=<contactName>]
                         [contactEmail=<contactEmail>]

    cwauthadmin removeOAuthClient
                         clientId=<cliendId>

Operations

CubeWerx Stratos Authentication Server operations are available through the "<deploymentUrl>/auth" endpoint, and can be invoked either via HTTP GET (supplying the parameters as part of the URL) or via HTTP POST (supplying the parameters in the body of the request with an application/x-www-form-urlencoded MIME type). The usage of HTTP POST is recommended for the "login" operation in order to prevent plaintext usernames and passwords from being visible in the URL. Responses that indicate a status in the response body will also report this status via a CwAuth-Status HTTP response header. Most of the operations respect the Accept HTTP request header and thus will return HTML by default if invoked through a web browser. JSON is typically returned by default if no Accept header is present. If a request to a CubeWerx Stratos Authentication Server contains cross-origin resource sharing (CORS) headers, then the origin of the request must be in the same CwAuth domain as the CubeWerx Stratos Authentication Server.

Auto

usage

    <deploymentUrl>/auth/login
        [?username=<username>]
        [&callback=<callbackUrl>]

Presents a simple HTML login page. When the user submits this page, the "login" operation (described next) is triggered.

If a username is provided, the username field is pre-filled-in with this value. If a callbackUrl is provided, then once the user has logged in successfully, a button is presented which allows the user to go to that URL, returning the user to the web application that invoked the login page.

Login (HTML page)

usage

    <deploymentUrl>/auth/login
        [?username=<username>]
        [&callback=<callbackUrl>]

Presents a simple HTML login page. When the user submits this page, the "login" operation (described next) is triggered.

If a username is provided, the username field is pre-filled-in with this value. If a callbackUrl is provided, then once the user has logged in successfully, a button is presented which allows the user to go to that URL, returning the user to the web application that invoked the login page.

Login

usage

    <deploymentUrl>/auth/login
        ?username=<username>
        &password=<password>
        [&format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

Authenticates the user for the current domain (i.e., the second-level domain name of the URL that the CubeWerx Stratos Authentication Server was invoked with) and logs him/her in by supplying the user agent (e.g., web browser) with a CW_CREDENTIALS cookie for that domain.

returns

If authentication is successful, a CW_CREDENTIALS cookie is returned in the response HTTP headers, and a "loginSuccessful" response in the requested format is returned in the response body. The response body includes unencrypted credentials. Also, the XML and JSON responses include an authorization token which can be passed to the various web services via an Authorization header (i.e., "Authorization: CwAuth <authorizationToken>") as an alternative way to pass credentials.

XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>loginSuccessful</Status>
        <CwCredentials>
            <Domain>xyzcorp.com</Domain>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <EMailAddress>jdoe@xyzcorp.com</EMailAddress>
            <AuthUsername>jdoe</AuthUsername>
            <AuthServer>https://xyzcorp.com/cubewerx/auth</AuthServer>
            <Role>User</Role>
            <Role>Administrator</Role>
            <AuthTime>2025-04-18T20:19:32.167Z</AuthTime>
            <Expires>2025-04-19T08:19:32.167Z</Expires>
            <LoginId>53vQyeTY</LoginId>
            <HasMaxSeats>true</HasMaxSeats>
        </CwCredentials>
        <AuthorizationToken>eyJhb...8hUPg</AuthorizationToken>
    </CwAuthResponse>

JSON:

    {
        "status": "loginSuccessful",
        "credentials": {
            "domain": "xyzcorp.com",
            "firstName": "John",
            "lastName": "Doe",
            "eMailAddress": "jdoe@xyzcorp.com",
            "authUsername": "jdoe",
            "authServer": "https://xyzcorp.com/cubewerx/auth",
            "roles": [ "User", "Administrator" ],
            "authTime": "2025-04-18T20:19:32.167Z",
            "expires": "2025-04-19T08:19:32.167Z",
            "loginId": "53vQyeTY",
            "hasMaxSeats": true
        },
        "authorizationToken": "eyJhb...8hUPg"
    }

HTML (if a callbackUrl is provided):

    (an HTTP redirection to the specified callbackUrl)

HTML (if a callbackUrl is not provided):

    (an HTML document showing the user's new credentials)

If authentication is unsuccessful, a response that indicates a status of "loginFailed" is returned. If unsuccessful login requests are occurring too frequently for this user, the login request is rejected and a response that indicates a status of "loginAttemptsTooFrequent" is returned. This protects the CubeWerx Stratos Authentication Server against brute-force password-cracking attempts. If the specified username has a maximum number of seats configured and there are currently no available seats, a status of "noMoreSeats" is returned.

Logout

usage

    <deploymentUrl>/auth/logout
        [?format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

Logs the user out of the current domain (i.e., the second-level domain name of the URL that the CubeWerx Stratos Authentication Server was invoked with) by requesting that the user agent (e.g., web browser) expire the CW_CREDENTIALS cookie for that domain.

returns

An empty CW_CREDENTIALS cookie with a cookie expiry time in the past is returned in the HTTP response headers, and a "logoutSuccessful" response in the requested format is returned in the response body.

XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>logoutSuccessful</Status>
    </CwAuthResponse>

JSON:

    { "status": "logoutSuccessful" }

HTML (if a callbackUrl is provided):

    (an HTTP redirection to the specified callbackUrl)

HTML (if a callbackUrl is not provided):

    (an HTML document indicating that the user has been logged out)

GetCredentials

usage

    <deploymentUrl>/auth/credentials
        [?format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

Returns the user's current credentials (i.e., the unencrypted contents of the user's CW_CREDENTIALS cookie) for the current domain.

returns

Either a "credentialsOkay", a "noCredentials", a "credentialsExpired" or a "credentialsInvalid" response in the requested format is returned in the response body. If "credentialsOkay" or "credentialsExpired", the response body includes unencrypted credentials. Note that a CW_CREDENTIALS cookie is not returned in the response HTTP headers, as this would be redundant. The "credentialsInvalid" response response is returned in situations where the user has credentials but they are not recognized by this authentication server.

XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>credentialsOkay</Status>
        <CwCredentials>
            <Domain>xyzcorp.com</Domain>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <EMailAddress>jdoe@xyzcorp.com</EMailAddress>
            <AuthUsername>jdoe</AuthUsername>
            <AuthServer>https://xyzcorp.com/cubewerx/auth</AuthServer>
            <Role>User</Role>
            <Role>Administrator</Role>
            <AuthTime>2025-04-18T20:19:32.167Z</AuthTime>
            <Expires>2025-04-19T08:19:32.167Z</Expires>
            <LoginId>53vQyeTY</LoginId>
            <HasMaxSeats>true</HasMaxSeats>
        </CwCredentials>
    </CwAuthResponse>

or

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>noCredentials</Status>
    </CwAuthResponse>

or

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>credentialsExpired</Status>
        <CwCredentials>
            ...
        </CwCredentials>
    </CwAuthResponse>

or

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>credentialsInvalid</Status>
    </CwAuthResponse>

JSON:

    {
        "status": "credentialsOkay",
        "credentials": {
            "domain": "xyzcorp.com",
            "firstName": "John",
            "lastName": "Doe",
            "eMailAddress": "jdoe@xyzcorp.com",
            "authUsername": "jdoe",
            "authServer": "https://xyzcorp.com/cubewerx/auth",
            "roles": [ "User", "Administrator" ],
            "authTime": "2025-04-18T20:19:32.167Z",
            "expires": "2025-04-19T08:19:32.167Z",
            "loginId": "53vQyeTY",
            "hasMaxSeats": true
        }
    }

or

    { "status": "noCredentials" }

or

    {
        "status": "credentialsExpired",
        "credentials": {
            ...
        }
    }

or

    { "status": "credentialsInvalid" }

HTML:

    (an HTML document showing the user's current credentials)

    (if a callbackUrl is provided, then the HTML response document will
    include a button which allows the user to go to that URL, returning the
    user to the web application that invoked the getCredentials operation)

RefreshCredentials

usage

    <deploymentUrl>/auth/refresh
        [?format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

Refreshes the user's current credentials and supplies the user agent (e.g., web browser) with an updated CW_CREDENTIALS cookie for that domain. The credentials are given a new expiry time to extend the current login session. Also, if the CwAuth server is the originator of the credentials, the credentials are fully refreshed from the database.

returns

Either a "credentialsRefreshed", a "noCredentials" a "credentialsExpired" or a "credentialsInvalid" response in the requested format is returned in the response body. If "credentialsRefreshed", a new CW_CREDENTIALS cookie is returned in the response HTTP headers and the response body includes the refreshed unencrypted credentials. If "credentialsExpired", the response body includes the original (expired) unencrypted credentials. Also (new in CubeWerx Stratos 9.8), the XML and JSON responses include an authorization token which can be passed to the various web services via an Authorization header (i.e., "Authorization: CwAuth <authorizationToken>") as an alternative way to pass credentials.

XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>credentialsRefreshed</Status>
        <CwCredentials>
            <Domain>xyzcorp.com</Domain>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <EMailAddress>jdoe@xyzcorp.com</EMailAddress>
            <AuthUsername>jdoe</AuthUsername>
            <AuthServer>https://xyzcorp.com/cubewerx/auth</AuthServer>
            <Role>User</Role>
            <Role>Administrator</Role>
            <AuthTime>2025-04-18T20:19:32.167Z</AuthTime>
            <Expires>2025-04-19T08:19:32.167Z</Expires>
            <LoginId>53vQyeTY</LoginId>
            <HasMaxSeats>true</HasMaxSeats>
        </CwCredentials>
        <AuthorizationToken>eyJhb...8hUPg</AuthorizationToken>
    </CwAuthResponse>

or:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>noCredentials</Status>
    </CwAuthResponse>

or:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>credentialsExpired</Status>
        <CwCredentials>
            ...
        </CwCredentials>
    </CwAuthResponse>

JSON:

    {
        "status": "credentialsRefreshed",
        "credentials": {
            "domain": "xyzcorp.com",
            "firstName": "John",
            "lastName": "Doe",
            "eMailAddress": "jdoe@xyzcorp.com",
            "authUsername": "jdoe",
            "authServer": "https://xyzcorp.com/cubewerx/auth",
            "roles": [ "User", "Administrator" ],
            "authTime": "2025-04-18T20:19:32.167Z",
            "expires": "2025-04-19T08:19:32.167Z",
            "loginId": "53vQyeTY",
            "hasMaxSeats": true
        },
        "authorizationToken": "eyJhb...8hUPg"
    }

or:

    { "status": "noCredentials" }

or:

    {
        "status": "credentialsExpired",
        "credentials": {
            ...
        }
    }

HTML:

    (an HTML document showing the user's refreshed credentials)

    (if a callbackUrl is provided, then the HTML response document will
    include a button which allows the user to go to that URL, returning
    the user to the web application that invoked the refreshCredentials
    operation)

EditUserInfo (HTML page)

usage

    <deploymentUrl>/auth/editUserInfo
        [?callback=<callbackUrl>]

Presents a simple HTML page allowing the user to change his/her e-mail address, name and/or password. When the user submits this page, the "editUserInfo" operation (described next) is triggered.

If a callbackUrl is provided, then once the user has successfully changed his/her information, a button is presented which allows the user to go to that URL, returning the user to the web application that invoked the editUserInfo page.

EditUserInfo

usage

    <deploymentUrl>/auth/editUserInfo
        [?username=<username>]
        [&email=<newEmailAddress>]
        [&firstName=<newFirstName>]
        [&lastName=<newLastName>]
        [&oldPassword=<password>]
        [&newPassword=<newPassword>]
        [&maxSeats=<maxSeats>]
        [&isEditable=<bool>]
        [&isEnabled=<bool>]
        [&format=<outputFormat>]
        [&callback=<callbackUrl>]

Changes the e-mail address, name and/or password of the current or specified user in the CubeWerx Stratos Authentication Server database. If an attempt is made to change the password and the current user doesn't have Administrator privileges, the old (current) password must also be supplied. If the current user has Administrator privileges, an arbitrary username can be specified. To remove a maxSeats limit, specify a negative number.

returns

If the operation is successful, an "editUserInfoSuccessful" response in the requested format is returned in the response body. If the request didn't specify a username, then the response body will include the updated credentials and an updated CW_CREDENTIALS cookie is returned in the response HTTP headers.

XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <CwAuthResponse>
        <Status>editUserInfoSuccessful</Status>
        <CwCredentials>
            <Domain>xyzcorp.com</Domain>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <EMailAddress>jdoe@xyzcorp.com</EMailAddress>
            <AuthUsername>jdoe</AuthUsername>
            <AuthServer>https://xyzcorp.com/cubewerx/auth</AuthServer>
            <Role>User</Role>
            <Role>Administrator</Role>
            <AuthTime>2025-04-18T20:19:32.167Z</AuthTime>
            <Expires>2025-04-19T08:19:32.167Z</Expires>
            <LoginId>53vQyeTY</LoginId>
            <HasMaxSeats>true</HasMaxSeats>
        </CwCredentials>
    </CwAuthResponse>

JSON:

    {
        "status": "editUserInfoSuccessful",
        "credentials": {
            "domain": "xyzcorp.com",
            "firstName": "John",
            "lastName": "Doe",
            "eMailAddress": "jdoe@xyzcorp.com",
            "authUsername": "jdoe",
            "authServer": "https://xyzcorp.com/cubewerx/auth",
            "roles": [ "User", "Administrator" ],
            "authTime": "2025-04-18T20:19:32.167Z",
            "expires": "2025-04-19T08:19:32.167Z",
            "loginId": "53vQyeTY",
            "hasMaxSeats": true
        }
    }

HTML:

    (an HTML document indicating that the information has been successfully
    updated)

    (if a callbackUrl is provided, then the HTML response document will
    include a button which allows the user to go to that URL, returning
    the user to the web application that invoked the editUserInfo operation)

ForgotPassword

usage

    <deploymentUrl>/auth/forgotPassword
        ?username=<username>
        [&format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

Indicates to the CubeWerx Stratos Authentication Server that the specified user has forgotten his/her password. An e-mail message is sent to the e-mail address registered for the user providing a URL that the user can click on to initiate a password reset. This URL is a call to the "resetPassword" operation (with a one-time authentication key), and is only valid for a limited time.

returns

A "passwordResetInitiated" response in the requested format is returned.

ResetPassword

usage

    <deploymentUrl>/auth/resetPassword
        ?username=<username>
        &authKey=<authKey>
        [&format=XML|JSON|HTML]
        [&callback=<callbackUrl>]

This is phase two of the "forgotPassword" operation, and is triggered via the URL that is sent out as a result of that operation. If the specified authKey matches the one that was set up by the "forgotPassword" operation, and it is within the allowed time frame, the password of the specified user is reset to a random value, and an e-mail message is sent to the user indicating what the new password is.

returns

A "passwordResetComplete" response in the requested format is returned.

GetPublicKey

usage

    <deploymentUrl>/auth/publicKey
        [?format=XML|JSON|HTML]

Returns a JSON representation of the public key of this CubeWerx Stratos Authentication Server. It is this key that must be propagated to the other servers in the domain so that they can verify the authenticity of credentials that originate from this server.

returns

A JSON representation of the public key of this CubeWerx Stratos Authentication Server is returned (with a MIME type of application/jwk+json). The format parameter controls only the format of the returned exception report if an internal error occurs.

OidLogin

usage

The oidLogin operation supports three separate modes of operation.

1) If the third-party client application has an OpenID Connect access token, it can provide this token either in the Authorization header (as a Bearer token) or as the value of the access_token query parameter. If a callback URL is also provided, the web browser will automatically be redirected to the specified URL after a successful authentication. Otherwise, the user's credentials are returned. This mode of operation doesn't require the CubeWerx Stratos deployment to be registered with the OpenID Connect server.

    <deploymentUrl>/auth/oidLogin
        [?access_token=<accessToken>]
        [&callback=<callbackUrl>]

2) The third-party client application can provide an issuerUrl parameter. If the CubeWerx Stratos deployment is registered with the specified OpenID Connect issuer and is appropriately configured, an OAuth 2.0 Authorization Code flow will be triggered. If an appSubpath parameter is also provided, the web browser will automatically be redirected to the specified application within the CubeWerx Stratos deployment after a successful authentication. Otherwise, the web browser will be redirected to a web page that displays the user's credentials.

    <deploymentUrl>/auth/oidLogin
        ?issuerUrl=<oidIssuerUrl>
        [&appSubpath=<appSubpath>]

3) As a redirect_uri callback during an OpenID Connect authorization request. In this case, the expected query parameters are code and state (as per RFC 6749, section 4.1.2).

    <deploymentUrl>/auth/oidLogin
        ?code=<code>
        &state=<state>

All three of these modes of operation will result in the web browser receiving a CW_CREDENTIALS cookie upon successful authentication, providing the user with a CubeWerx Stratos identity complete with the access-control roles, etc., that have been assigned to it.

Errors

For most operations, if an error occurs, an exception report in the requested format is returned in the response body. The returned HTTP status code will indicate whether the error is a client-side error (4xx) or a server-side error (5xx).

XML:

    (an OGC OWS 1.1 exception report)

JSON:

    {
        "status": "exception",
        "exception": {
            "format": "CubeWerx_Error",
            "version": "<productVersionNumber>",
            "entries": [
                {
                    "prefixText": "AUTH",
                    "message": "<level 1 error message>",
                    "msgLang": "en",
                    "traceInfo": "<source code location information>"
                },
                {
                    "prefixText": "AUTH",
                    "message": "<level 2 error message>",
                    "msgLang": "en",
                    "traceInfo": "<source code location information>"
                }
                ...
            ]
        }
    }

HTML:

    (an HTML document providing details about the error)

MaxSeats configuration

By default, there's no limit as to how many times a particular CwAuth user can be logged in at any one time. However, it's possible to impose such a limit by specifying a maxSeats value for the username. If that user is already logged in that many times (i.e., already occupies that many login seats), the CubeWerx Stratos Authentication Server will deny any more login attempts (by returning a "noMoreSeats" status) until a seat is released. A seat is released when an instance of the user logs out, either explicitly through a "logout" operation, or implicitly when a set of credentials expires.

This is generally set up for situations were multiple people are given access to the same user account, but where the license agreement allows only so many people to use it at any one time.

In order for this mechanism to work effectively, credentials should be configured with a short validity duration (e.g., 10 minutes), and the application should issue frequent "refreshCredentials" requests (e.g., every 2 minutes) to the CubeWerx Stratos Authentication Server. Furthermore, the application should detect when a user has been inactive for while (e.g., 10 minutes), and automatically issue a "logout" request on the user's behalf. (Alternatively, it could just stop issuing "refreshCredentials" requests and let the credentials eventually expire on their own.) This avoids login seats being taken up by inactive users.

It's possible to have some usernames with a maxSeats limit and other usernames without such a limit. Since there's no contention for login seats in the latter case, there's no need for a short validity duration for those users. To facilitate this flexibility, there are two separate configuration parameters for configuring this validity duration: auth.credentialsValidityDuration (for usernames without a maxSeats limit, default: 12 hours) and auth.credentialsValidityDuration.withMaxSeats (for usernames with a maxSeats limit, default: 10 minutes). Also, an application may choose to be less aggressive in automatically logging a user out after a period of inactivity if that username doesn't have a maxSeats limit. The application can determine whether or not a username has a maxSeats limit by consulting the "hasMaxSeats" property (default: false) in the credentials object returned by a "login", "getCredentials" or "refreshCredentials" operation.

HttpBasic-to-CwAuth bridge

Since the CwAuth login mechanism is implemented as a web service that utilizes HTTP cookies to store the user's authenticated identity on the client side, non-web-based (i.e., desktop) applications are not directly compatible with it (unless they're augmented with specific support for it). However, many desktop applications have built-in support for the HTTP Basic Authentication mechanism (RFC 7617) when connecting to web services. To allow such desktop applications to connect to CubeSERV services with a CwAuth identity, CubeSERV comes equipped with an HttpBasic-to-CwAuth bridge.

By default, applications that wish to connect to CubeSERV in this way must connect to CubeSERV via its "htcubeserv" endpoint. This endpoint will perform HTTP Basic Authentication negotiation, and will internally convert the resulting HTTP Basic identity into a CwAuth identity. The cubeserv.httpBasicAuthentication.mode configuration parameter specifies the behaviour of this endpoint.