Implementing authentication in CRM Online

In this article

    This article discusses the general workflow, orchestration and implementation of client authentication.

    Partner Identifiers

    Partner applications have two unique identifiers: ApplicationIdentifier (AppId) and ApplicationToken (AppSecret). The latter one is considered a password and must be stored as such.

    • Application Identifier: uniquely identifies the application used, and used by the SuperOffice CRM Online to know where to redirect a user. 
    • Application Token: must be supplied when invoking any of the SuperOffice CRM Online web services.

    Normal User Authentication 

    No application is allowed to ask users for their credentials, ever! 

    There are three steps all application must do to authenticate users. 

    1. Forward users to the SuperOffice online login page to authenticate.
    2. Receive the authentication token when the login page redirects the user back to your application.
    3. Validate the authentication token.

    The following is the bare minimum required to forward a user to the SuperOffice login page, a hyperlink:

    OLD FORM (do not use anymore):

    http://{env}.superoffice.com/login/?app_id=YOUR-APP-ID

    OAUTH2 (preferred): 

    https://{env}.superoffice.com/login/common/oauth/authorize?response_type=id_token token
    &client_id=YOUR-APP-ID&redirect_uri=YOUR-REDIRECT-URL&scope=openid&state=12345
    &nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

    The difference of use between OLD FORM and OAuth2 URLs is the HTTP Response sent to the Redirect URL.

    The OLD URL request receives a JWT or SAML token in the body of the response with claims, including a Ticket credential.

    The OAuth2 URL request, which is an Implicit Flow request, returns a URL fragment containing an JWT id_token, with tentant and user claims, plus an access_token credential. See the SuperOffice OpenID Connect article for more details.

    Note that the sub-domain is different for each online environment: development, stage and production. It's very likely that the application identifier will be as well. The application identifier is necessary to link the user to an application definition where the redirect url is specified.

    Receiving the Authentication Token

    Old Form (use OAuth 2.0 instead)

    The authentication token is returned in an HTTP Response that contains a form in the body:

    <form action=”redirecturl” method=”post”>
       <input type=”hidden” name=”key” value=”<value>” />
    </form>

    The form action is populated with the applications redirect URL. The method will be either POST or GET, and also comes from the application definition.

    There will be one hidden input type with a name equal to either SAML or JWT, and the value will be the authentication token of the corresponding type.

    It's up to the receiver to extract the value and validate the security token using the public certificate provided by SuperOffice.

    All applications must validate the security token each time it is received to ensure there are no attacks in between when the authentication request went out and the authentication response was received.

    OAuth 2.0

    For indepth details for OAuth2, please read the SuperOffice Online OpenID Connect article.

    System User Authentication

    System users are used for data processing that do not require user interaction. In order to obtain a valid system user ticket, you must first use the system user token that was provided in the callback when the administrator installed the application. Exchange the system user token for a system user ticket. SuperOffice CRM Online exposes one WCF SOAP endpoint for conducting the exchange: https://onlineenv.superoffice.com/login/services/PartnerSystemUserService.svc.

    As seen in Figure One, the soap envelope contains two headers, and an AuthenticationRequest element in the SOAP body.

    The ApplicationToken element is required and is populated with the application token issued when the application was registered.

    The ContextIdentifier element is also required and must contain the customers' identifier who has at least one prior authorized access for this application. The application approval occurs by the customers' administrator when the application was first installed.

    Figure One: XML SOAP Request using Fiddler2

    The AuthenticationRequest contains two elements: SignedSystemToken and ReturnTokenType.

    A System User Token remains the same and will not change for the duration of the application. It is returned to the application during the original approval response when the customer administrator installed the application. The application is responsible for taking the system user token claim and storing it for later use.

    The System User Token is not what the AuthenticationRequest expects in the SignedSystemToken element. Instead, the SignedSystemToken element value must contain a composite of elements that includes the System User Token.

    The format of the SignedSystemToken element value is:

    1. plain text system user token
    2. a period
    3. a UTC date time formatted as four digit year, leading zero based month, leading zero based day, leading zero based hour and leading zero based minutes
    4. a period
    5. a Base64 encode a signed version of numbers #1, #2 and #3.

    So the first step to constructing a SignedSystemToken is to:

    1. concatenate the first three items.
    2. using the partners private certificate key, sign the concatenated items.
    3. base64 encode the result of the signed items.

    The result will then look something like the following:

    System User Token.YYYYMMDDHHMM.mwhpYcNBfFqEaL0uLkCwXB99sM/Wo7DOnhjRwsmwNAd2EmBM1z+Co=

    Another way to describe is as follows (PHP): 

    $systemUserTokenAndTime = Application Name-pzqc70604i.201511111342
    $signature = signVariable($systemUserTokenAndTime)
    $signedSystemToken = $systemUserTokenAndTime + "." + base64_encode($signature)

    The ReturnType element value must contain the format of the security token returned in the response. This must be either SAML or JWT.

    Validating the Authentication Token

    Whether authenticating a normal or system user, all applications must validate the response token from SuperOffice using the public key provided by SuperOffice.

    All security token responses are base64 encoded strings of either a SAML or JWT token. The steps involved with validating a token are as follows:

    1. Decode the token from Base64 to a string. This results in either an XML or JSON string.
    2. Use an appropriate certificate validation library and the public superoffice certificate to validate the XML or JSON token.
    3. Once proven valid, accept the Claims and proceed accordingly. 

    SuperOffice provides the following SuperOffice.Crm.Online.Core nuget for processing online requests. The package contains the following assemblies:

    1. SuperOffice.Online.Core
    2. SuperOffice.SuperID.Client
    3. SuperOffice.SuperID.Contracts

    SuperOffice providers a .NET helper libraries available in the example downloads.

    The main class for processing tokens is called SuperIdTokenHandler, and resides in the SuperOffice.SuperID.Client dll. SuperIdTokenHandler abstracts away the slight differences involved validating SAML and JWT tokens.

    When you need to deploy to an environment where you do now have full control of, or access to, the certificate stores, you may need to override the default want certificates are resolved to validate the SAML or JWT security tokens. In that case, be sure to read up on how to do this in the Security Tokens and Certificate Validation article. 

    SuperOffice DevNet online example downloads also contain examples how to validate tokens using PHP. None of the example downloads are considered production environment ready and only available as an example.

    Validating tokens requires knowledge of working with and configuring certificates. More information about managing certificates can be found on the example downloads page.