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 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 Online as a User

    SuperOffice has 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.

    SuperOffice doesn’t know who they are, so 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 tokens 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 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 online, you need to register your company as a partner, and register your app as a partner app. Currently this is a manual process, but as we get further down the line this will be handled using a form on DevNet.

    Your company registration tracks:

    • Company Name
    • Technical Contact address & phone – someone we can call if something stops working.
    • Admin Contact address & phone – someone we can call about non-technical stuff.

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

    Registering your app is a similar form – currently done manually.

    • Application Name & Description
    • Application Id (Public)
    • Application Token (Secret)
    • Authorization Level – how does the app connect to the services?
    • URL to your app
    • Claims the app wants returned from successful authentication

    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 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.

    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 on this particular customer.
    • NetServer_URL = The 73 web service endpoint 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.

    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.

    The redirect looks like this:

    https://sod.superoffice.com/login/?app_id=706d3390-e66f-11e3-9eff-1f04b455658f

    The app_id part tells the SO Login page where to go once it has finished figuring out who the user is.

    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.

    Currently the algorithm depends on an internal SuperOffice certificate with a non-standard signature algorithm, so you can’t use the standard JWT libraries to check the signature.  

    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.

    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.