In the last two parts of the Sitecore Identity series, I described the basics and an understanding of the architecture and how IdentityServer4 is embedded and used in Sitecore 9.1+, the second part was a demo for adding a web client that authenticates itself against the Sitecore Identity (meaning that a custom web application uses Sitecore as the login method think like Login using Facebook or any other Identity Provider).
The third post of the series is a bit new, as there aren’t any samples (that I could find). I will show how to add a native mobile app client (iOS for this post but Android works the exact same).
This will enable you first to authenticate against the Sitecore Identity, then secondly (later posts coming) consume protected APIs (whether Sitecore native or custom ones).
Recap
So let’s recap how the identity system works and the moving parts of it.
1- There is an Identity Provider, which holds users, passwords, information about them, should be a trusted party that knows how to authenticate.
2- There are a few protected resources (data called identity resources, and methods called Api resources).
3- There are Clients that want to consume these protected resources.
How it works again?
0- Step zero (pre requisites) a Client configuration needs to be added at the Identity Provider so when it comes back for permission the IdP would know how to handle it, where to redirect, what are the protected resources it can ask for, what is the mechanism used to secure, verify and send tokens back to the client and some other details we’ll see in the configs in a bit.
1- Client app connects to the Identity Provider and asks for permission (access) to get some or all of those protected resources (scopes).
2- Control is at Identity Provider now (through a web redirect or a web popup) and asks the user to login and let’s him know what protected resources the client wants to access (can optionally ask for consent).
3- Client app get control back with a token that can usually have both (data) and permission to access methods (id_token and access_token).
Sitecore side Add the configuration
Same as we discussed before, we add client configuration at the identityServer.xml, which resides at the <instance>.identityserver\sitecore\Sitecore.Plugin.IdentityServer\Config folder.
Notable properties for native apps:
AllowOfflineAccess: This configuration when set to true allows the client app to keep and request a refresh token, which is used later to request a new token when the one it has expires, it can do this silently (without redirecting the user to relogin to the IdP.
RedirectUri: This piece of information is very important, in native apps the redirectUri needs to a schema based uri, that should be registered inside your iOS/Android app so the redirection happens correctly, details here.
AllowedGrantType: This property is a collection that accepts one or many grant types, one important thing to note here, that mobile native apps Must run on authorization_code grant type. It provides a way to retrieve tokens on a back-channel as opposed to the browser front-channel. It also support client authentication.
RequireClientSecret: In OAuth1.0 there was a required secret with clients, but in OAuth2.0 it became optional, and actually not recommended to add use client secrets for public apps (mobile and javascript / ones that don’t run on a server)
Building the client app
As I mentioned before the scope of this post will be adding an iOS client only, but Android is pretty much the same.
In the world of web, I mentioned the great IdentityModel open source project written in .NET (and supports all platforms, if you build Xamarin apps go ahead with that).
In the mobile native world there is a similar, popular well written and widely used open source project AppAuth it has iOS, Android and Mac implementations.
For the sake of this post, I will use the sample app that comes with the library. Assuming you are an iOS developer I am sure you already have cocoapods installed (a package manager something similar to npm in the world of Apple dev iOS/MacOSX) .
All you need to do (which I have done) go to your projects directory and run pod try AppAuth in your preferred command line tool , I use iTerm if you haven’t tried it yet, give it a spin.
Once you have your project ready, go to the AppAuthExampleViewController.swift file and add your parameters, I have added the full file as a github gist here.
https://gist.github.com/AmrElsehemy/59b2b30c98125fe2352995cdce07d7ca
Notable changes to make it work!
1- Set the issuer url, this is the url of the Sitecore Identity server (!NOTE: this is not the instance url, it’s the identity server) at line 27
2- Set the client id, this has to match the one you just configured in SI in our case AwesomeAppId at line 35
3- Set the redirectUrl to the same one you added in the config, usually this also needs to be registered as the schema url for your app in the info.plist (not required to make this sample work) this to be found at line 42.
4- Sitecore Identity has it’s own scope when it comes to profile data, so you need to change the scope request from profile to sitecore.profile to make it work changes at line 386.
How it looks
It start from Auto login (which tries to discover the connect/authorize/token urls on it’s own).
Then opens an embedded web view so the user can enter his sitecore credentials
Finally upon correct login, the web view closes and returns with the correct access token so the app can use it to understand information about the logged in user or alternatively use it as a Bearer token to get more information from APIs protected by Sitecore Identity server.
References
- https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/
- https://tools.ietf.org/html/rfc7636
- https://aaronparecki.com/oauth-2-simplified/
- https://tools.ietf.org/html/draft-ietf-oauth-native-apps-07
- https://github.com/openid/AppAuth-iOS/blob/master/Examples/README-IdentityServer.md
- https://guides.cocoapods.org/using/getting-started.html
Leave a Reply