Registering your app for CRM Online

In this article

    To get your unique application identifier and token needed for developing your app, you need to register your app idea with us by completing our app registration form. 

    Register your app: 
    Please complete the form Register app 

    Here's what happens after you register your app: 

    1. You'll receive the application identity and token from SuperOffice that you need to build your app.
    2. You will also gain access to our sandbox environment and a test-installation you can use to test your application.  
    3. When you believe your app is ready, you can submit it for our certification tests. After passing these tests, your app can be listed in the App Store. Custom apps only need to be validated.   

    The registration form

    The information you need to provide when registering include:

    1. Application name and description
    2. URLs to your application
    3. Type of desired security token (SAML or JWT)

    1. Application name and description

    When listed in the App Store, these fields are shown to the users in nicely formatted web pages.

    This means that it’s helpful to think of a name that makes sense to the end-users. You can start off with a project name. However, once your app is listed and used by customers, it is not possible to change the name. It’s helpful to have this in mind from the beginning.  

    Similarly, you need to describe your app in terms of who it is for, what it does, key features and requirements. This can easily be changed later so try to describe it even if you are not 100% sure about everything or ready with a product marketing text.  

    2. Application URLs 

    You also need to define a set of URLs for your application. These URLs will redirect a user when they click the buttons on your app entry.

    To be more specific: When users visit the SuperOffice App Store, what they see depend on whether they are signed in or not. When signed in, a user new to this app will see an Install button. A user with the app already installed will see a Configure button and an UnInstall button.

    These buttons lead the user to the URLs you define when registering your application.

    Therefore, you must provide the following five URLs: 

    1. Login callback URL - the SuperOffice login page will post the claims and login results to this page.
    2. Error callback URL - you can also provide an error URL to show when login is unsuccessful.
    3. Application install URL – where the App Store will link to when the user clicks BUY
    4. Application configure URL – where the App Store will link to when the user clicks CONFIGURE
    5. Application uninstall URL – where the App Store will link to when the user clicks UNINSTALL

    The callback URL can be configured as POST or GET request – depending on what you prefer. However, POST is considered more secure because the parameters are not exposed to proxies or browser caches.

    When filling in the form, please make sure to describe the application and it's technical requirements as best as you can. 

    If your application only runs as a background task, make sure to read about system users on the application models page.

    Receiving application identity and token

    Once SuperOffice has registered your application into the SuperOffice Online Development Operations Center (SOD OC), you will receive an email with the following information:

    1. Application Id
    2. Application token
    3. Certificates

    a) Application Id

    Your app uses the Application Id when authenticating. It is sent as a query string in the request sent to SuperId every login request. It identifies your application (and you as a partner).

    b) Application token

    The Application Token is a secret token that must not be shared. The token identifies your application in each web service request sent to SuperOffice web service endpoints.

    c) Certificates 

    Certificates are required to validate security tokens issued by SuperOffice SuperId. Certificates ensure that all communications with SuperId are secure and can be trusted.

    Even though all of our communications are protected by encryption over SSL, certificates provide an additional layer of protection and ensure identity of the origin server in order to prevent active snooping and modification of messages on the network and internet.

    You may download the certificates for SOD here.

    In return, you'll receive the application identity and token from SuperOffice that you need to build your app. In addition, you will gain access to our sandbox environment and a test installation you can use to test your application.  

    When you believe your app is ready, you can submit it for our certification tests and after passing this your app can be listed in the store.  

    Changes to your app definition

    We do not currently support self-service of your apps, so if you want to make changes to the whitelisted redirect urls, CORS or which Services endpoint is returned, please use this form.

    ApplicationId and application token usage

    This is how it works: 

    1. User navigates to the SuperOffice CRM Online App Store.
    2. User clicks on Install of an application and is redirected to SuperId.
    3. User is redirected to SuperId with the ApplicationId for authentication and application authorization.
    4. SuperId looks up the InstallURL by ApplicationId and redirects the user to the Partner App InstallUrl with a security token.
    5. Partner application receives SuperID request and SAML token. Partner app validated the token using SuperOffice issued certificates and then extracts customer claims.
    6. Partner application interacts with User for installation requirements, i.e. purchase, configuration settings, etc.
    7. Partner application provisions itself into customer tenant using Application Token in all web service requests.

     

    Security token validation    

    SuperOffice issues a security token as either a Security Assersion Markup Language (SAML) or JSON Web Token (JWT).

    Included in the email from SuperOffice are three public certificates that must be used to validate a security token issued by SuperId.

    When used to validate a security token, certificates ensure a secure connection between the partner application and SuperOffice, as well as guarantee that nothing and no one in the middle tampered with the traffic while transitting the internet.

    Learn more about security token validation

    There is more documentation about how the Security Token Validation works in the online SDK, as well as sample code that demonstrates how to validate tokens in all of our examples above.

    If you have not done so already, it is highly recommended that you read more about the different deployment environments and how your applications are expected to perform.