Security and authentication

In this article

    This article describes SuperOffice CRM Online application authentication. In particular, we explain why SuperID exists and how it works with Google/Office 365 to handle log in details for you as an example. The article is inspired by Authentication Protocols, Web UX and Web API

    Traditionally

    To log in to SuperOffice you present a username and a password. SuperOffice checks the password against the hashed password in the database and lets you in if the two match.

    SuperOffice CRM Online log-in page

    The SuperID login page handles username + passwords, and checks them against the user’s SuperOffice database.

     

    Federation

    This is fine so long as SuperOffice is the most important thing in the universe.

    When Google or Office365 are the most important things in the universe, we can’t use the password stored in the database any more. The password is not accessible to us anymore. We can’t check it directly – we can just delegate the whole username/password problem to Google/Office365.

    SuperOffice wants to access user information and store documents in the Google or Office365 cloud. In order for SuperOffice to access your part of the Google or Office365 cloud, there needs to be a link between your SuperOffice identity (stored in the SO database) and your Google/Office365 identity.

    This is called Federation – SuperOffice and Google/Office365 share the same idea about who you are. 

    Google explains how its login system works here: https://developers.google.com/accounts/docs/OAuth2Login

    Office 365 is similar: http://blogs.msdn.com/b/exchangedev/archive/2014/03/25/using-oauth2-to-access-calendar-contact-and-mail-api-in-exchange-online-in-office-365.aspx

    Both use the OAuth 2.0 protocol. Both require that developers register their applications with their central registry. This registration makes it harder for hackers to steal the results of your login.

    Logging in to SuperOffice CRM Online as a User

    SuperOffice is registered as an application with both Google and Office 365 so that we can use their services for logging in, and get the authentication request sent back to us.

    When a user wants to log in to SuperOffice using Google or Office 365, they first go to the SuperOffice login page where they are shown a login page. Once they user has filled in the username, we can check if their account is connected to Google or Office 365. If they are connected to Google, we show a “Login with Google” button instead of the password field.

    The SuperOffice login page sends the user off to the Google login page, with a note to come back to the SuperOffice login page once Google has figured out who the user is.

    Hopefully Google sees that the user is already logged in to Google, and returns to SuperOffice with a set of claims. If the user is not logged in then the user will see a Google login form.

    Google then checks that the user has given the SuperOffice login page access to their e-mail address. If they haven’t done so before, they get a second screen from Google, asking for permission to give access to SuperOffice. 

    Once Google is sure it know who the user is, and the user has allowed the app making the request to access the user’s information, Google sends the information back to the app that made the request – in this case back to the SuperOffice login page.

    Note that Google checks the Google database for app registrations to find the right URL to send this information back to. This makes it hard for a 3rd party to intercept the authentication results.

    The SuperOffice login page receives the user’s e-mail and security token from Google, and can call Google to verify that these are valid. The SuperOffice login page now knows what Google knows, and can therefore let you in to the SuperOffice application.

     

    Logging in to SuperOffice CRM Online as an Application

    When partner apps want to connect to SuperOffice, SuperOffice is in the same position as Google. SuperOffice needs a central registry of partner apps that want to use SuperOffice to authenticate, so we know where to send the results of the login request.

    In order to talk to SuperOffice CRM Online, you need to start off by registering as a developer so you get a sandbox environment in our development environment (SOD), and register your app as either a standard or custom app. If you or your company are unknown to us, we will ask for a more information before we create your sandbox environment.

    In the future SuperOffice will also keep your company description and logo for use in the App Store.

    SuperOffice stores the registration of your app, and the following information:

    • Application Name & Description
    • Application Id (Public)
    • Application Token (Secret)
    • Authorization Level – how does the app connect to the services?
    • URL to your app (Redirect URL)
    • Other whitelisted redirect URLS

    App Name and Description

    These are just for book-keeping at the moment. When the App Store goes live we will show these to the users in nicely formatted web pages.

    The App Store will add information about screenshots, YouTube links, FAQ and Forum links, and multiple-language support to all this.

    Application Id and Token

    The Application Id and Token are generated by SuperOffice and are used by your app when authenticating.

    The App Id is sent to SuperId in the browser with every login request. It identifies your application (and you as a partner) for every login request you issue.

    The App Token is a secret that is used to identify your web service requests. The Token is different from the Id. The App Token is sent from your server directly to the customer’s web services API on every web-service request from your app. The App Token should not be passed via the browser. It is reserved for server-to-server web-service calls.

    Changing either the AppId or the AppToken will automatically invalidate existing applications until they are updated with the new id and token values. It does not invalidate your applications as such – any web panels you have installed continue to exist. Your web panels will continue to call your web app as before.

    The only problem is that your web app will attempt to log in via SuperId with the old (invalid) AppId. Updating your web app to use the new AppId and AppToken will fix the problem.

    Authorization Level

    This determines who can approve your app for access to the customer’s web services.

    • Explicit – must be manually configured by SuperOffice operations.
    • Admin – Customer admin must approve the app. This is the default.

    These two authorization levels are also defined but not in general use:

    • User – Any user at the Customer can approve the app.
    • Implicit – No user approval is needed. Reserved for SuperOffice use.

     

    URL for the App

    You should provide several different URLs for you app:

    • Login Callback URL - the SuperOffice login page will post the claims and login results to this page.
    • Error Callback URL - You can also provide an error URL to show when login is unsuccessful.
    • Application Install URL – where the AppStore will link to when the user clicks BUY
    • Application Configure URL – where the AppStore will link to when the user clicks CONFIGURE
    • Application Uninstall URL – where the AppStore will link to when the user clicks UNINSTALL

    The CALLBACK URLs can be configured as POST or GET URLS – depending on what you prefer.

    POST is considered more secure, since the parameters are not exposed to proxies or to browser caches.

    For this example, we define the Login Callback URL as POST to

    https://app.partner.com/app/LoginRedirect.aspx

     

    Claims that you want returned from SuperOffice Login

    You can specify one or two claim types you want returned – Security Assertion Markup Language (SAML) or Javascript Web Token (JWT). Each token contains the following claims:

    • Ticket = SuperOffice ticket, representing the current user credential on this particular customer. Not included in OAuth flows.
    • NetServer_URL = The SOAP web service endpoint for the current customer site.
    • WebAPI_URL = The RESTful endpoints for the current customer site.
    • Email = The current user’s e-mail address
    • CTX = Context value (Current Customer id).
    • System User Token = A string used to exchange for a system user ticket credential.

    The tokens are returned to you by editing the DefaultRedirectUrl in the Operation Center.

    These form arguments are posted to the RedirectUrl you register for your app.

    So we will get a POST to https://app.partner.com/app/LoginRedirect.aspx with the form fields defined above when the user has successfully logged in to our app via SuperId.

    System User Tokens

    A system user token is not used for direct accesss to any customer tenant web services. System user tokens are a means to exchange with SuperId a system user token for a system user ticket. It is then the system user ticket which is used for access to the customer tenant. A system user token is only generated if the application definition has the system user token functionality enabled. A system user token is also only created and added as a claim when a customer administrator has successfully authenticated and approved the application for the tenant.

     

    A Day in the Life of a Partner App

    Your web application is sitting on a web server (app.partner.com on HTTPS port 443), waiting for a request. Port 80 (HTTP) cannot be used due to the lack of security. Read more about CRM Online security Enhancements

    Suddenly a request comes in for “/homepage” from out of the cloud.

    Your web application has no idea who is asking for “/homepage” – there is the IP address it came from, but there are no cookies or anything else we can see on the request. We could send back a 401 Unauthorized response to ask the user for a username + password, but that seems a bit rude.

    Instead we can redirect the request to someone who might know who is making the request, with a hint that they can send that information back to us once they know.

    Example:

    OLD FORM (do not use anymore):

    http://sod.superoffice.com/login/?app_id=YOUR-APP-ID

    OAUTH2 (preferred): 

    https://sod.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 id_token, with tentant and user claims, plus an access_token credential. See the SuperOffice OpenID Connect article for more details.

     

    The app_id part tells the SO Login page where to go once it has finished figuring out who the user is. Using the old form, you do not have to, but can explicitly define a redirect_url parameter to the query string. 

    Before we redirect off the SO Login page, we remember the original request URL in a cookie or session state – so that when we come back later, we can try the original request again.

           OriginalURL = /homepage

    SuperId Login Page

    The SuperOffice Login page can check its cookies (these cookies are not available to the partner domain) and see if the user is logged in. If not, then the user gets the login form again.

    The SuperOffice Login page may determine that you need to use Google to log in, and so SuperOffice sends you off the Google, with a note for Google to come back to SuperOffice Login page once it is done. The note also requests that Google provides the logged in user’s e-mail address and an authentication ticket.

    This part of the login dance is the same as logging in to SuperOffice. Google does not know that we are acting on behalf of the partner app. Google only has a relationship to the SuperOffice application.

    Google can hopefully check its cookies and log the user in without further interaction.

    Google authenticates the user as user@example.com

    Once Google is satisfied, it sends its claims back to the registered application URL – back to the SuperOffice login page, which sees that the response is marked as starting from app.partner.com (thanks to the app_id in the original App.Partner request to SO Login).

    Consent Form

    The SuperOffice login page looks up the partner application registration in its own system, and sees if the partner app is authorized to access this user’s information. If the user or the user’s administrator have not authorized the app, then the user may be shown a consent form similar to the Google approval form. 

    Logged In Successfully

    Assuming the partner app is authorized to access the customer’s site, the SuperOffice login page takes the returned claims from Google and parses them into a standard format, because it turns out Google and Office 365 return their claims using different systems. It fills in any extra information that the partner registered for its app (like the URL to the web services, or the user’s NetServer session ticket), and sends the result in a standard format back to the registered end-point for the partner app.

     

    These form fields are the fields we configured for the callback when we registered the redirect URL for the partner app earlier. The secret field contains the NetServer ticket for example.

    The partner’s LoginRedirect.aspx must verify that the claims are really from SuperOffice and not from some hacker with a black hat.

    Verifying Claims

    We can go to http://jwt.io/ to dig into the Javascript Web Token part of the –which comes in three parts – Base64 encoded and separated by periods:

    1. Algorithm header
    2. Claims
    3. Signature hash

    The algorithm tells us how the signature is computed, and what format the claims follow.

    { "typ": "jwt",
      "alg": "cert" }

    SAML and JWT are the tokens that SuperOffice supports – SuperId will map Google and Office365 claims to the SuperOffice format when federating, so you don’t have to deal with differences in claim formats.

    The claims in a JWT are a JSON structure mapping keys to claim values:

    { "http://schemes.superoffice.net/identity/email": "user@example",
      "http://schemes.superoffice.net/identity/identityprovider": "superoffice",
      "http://schemes.superoffice.net/identity/netserver_url":
    https://sod.superoffice.com/Cust8845/Remote/Services73/",
      "aud": "spn:1501052557",
      "sub": "user@example"
    }

    The signature block lets the client verify that the claims have not been tampered with. It’s a hash of the base64 encoded strings, according to the algorithm defined by the JWT standards.

    Receiving Claims from SuperId

    The partner’s LoginRedirect.aspx page can set cookies or session state to remember the e-mail and ticket information passed back from SO Login.

    The LoginRedirect.aspx page can look in the original URL it remembered before redirecting to the SO Login page. The LoginRedirect page then redirects the browser back to the original URL /homepage

    The app.partner.com web server gets the same request for /homepage that started the chapter, but this time it has additional information attached in the cookies or session state (depending on where LoginRedirect stashed the information).

    The partner app can now take the claims and connect to the NetServer web services (given by the netserver_url claim) using the ticket claim, and start providing the service that the user is paying for.

    What happens now is up to the app.  It might record the user’s usage of the app for billing purposes. It might check the user’s licenses, or get the customer’s SuperOffice serial number from the NetServer session.

    The partner app can configure the webservice end-point to the NetServer URL and connect to the customer’s system, using the NetServer ticket from the claims.

    Hosting Applications in Superoffice

    There are cases where, in the SuperID user repository,  a single individual has one user account associated with multiple online installations.

    Under those circumstances, after successfully authenticated, the user is presented with a selection of installations to navigate to. 

    Under some circumstances this is the prefered behavior, however, in the case where an application is hosted in a SuperOffice Web Panel; and therefore inside a known tenant, having a true single sign-on (SSO) experience is the preferred flow. 

    SOD-MultipleTenants.PNG

    In there case where the application is hosted inside a SuperOffice web panel and the user should have a true SSO experience, change the applications OAuth 2.0 endpoints to include the tenants customer identifier to bypass the tenant selection screen.

    That means instead of using the following generic endpoint:

    https://sod.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

    In the web panel's URL, use the <uctx> template variable to get the customers context identifier and include that in the endpoint.

    https://sod.superoffice.com/login/{contextIdentifier}/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
    
    // example
    
    https://sod.superoffice.com/login/Cust12345/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

    This will ensure the web panel application provides the user with seamless SSO experience.

    Summary

    SuperOffice has registered its login page with Google and Office 365 – it handles communcation with Google and Office 365 on the partner’s behalf.

    Partners must register their apps with SuperOffice so that SuperOffice knows where to send the responses it gets back from the cloud.

    Partners must register what token type their apps would like returned from the login page.

    Authentication in the cloud is not simple – there are many actors involved. It is not just a username and password that you can stash somewhere for re-use later.