- Prepare Domino Server
- Generating the update site yourself (from the sources)
- Implementing a new resource (Rest Service)
- The sample resource application
- TODO
This project aims at providing a set of Domino OSGI plugins that allows you to write an OAUTH2 resource server. It uses the dom-spring project, allowing you to write your services as standard Spring Rest controllers.
The Rest Services will have to be protected by an oauth2 access token. The token must be passed in the HTTP header "Authorization", using the "Bearer" schema :
Authorization: Bearer the_oauth2_access_token
The access token will be interpreted using the oauth2 authorization server introspection endpoint, or - in a near future - by decoding it using a public key (if it is a JWT).
The details of the token will then be made available to your plugin as a injectable bean named "BearerContext" : This bean will give you access to the name of the logged in user, the authorized scopes, and every information made available in the token. But if its "sub" property (the logged in user) correspond to the name of a regular Domino User, it will also open a standard NotesSession object for this user.
Note that when implementing servlets as OSGi plugins (this is what dom-spring is doing), you configure an "alias" that will make the servlet available at multiple urls :
- At the root of the server : http://domino_server/your_alias
- At the roor of EVERY nsf : http://domino_server/any_db.nsf/your_alias
When using a context path that reference a nsf database, if the "Authorization" HTTP header is present, Domino will expect it to contain the user login and password. But in our case, we will send this header with the oauth2 access token in it. For this reason, this framework will make the servlet respond when only called from the root of the server.
The (dom-spring)[https://github.com/lhervier/dom-spring] plugins must be deployed into your Domino Server. Documentation on how to deploy the plugins is available in the README file of the project on git hub.
The procedure is almost the same as for the dom-spring plugins.
First, download the latest update site from the github release page of this project, and unzip it where you want.
Then, create a new database named "Oauth2ResUpdateSite.nsf" (you can name it the way you want) on your server, using the "Eclipse Update Site" advanced template.
Open the database with your Notes client, and click on the "Import local update site" button. Go select the "site.xml" in the unzipped version of the update site.
It is recommanded to disable the "sample" feature.
Add (or update) the notes.ini variable "OSGI_HTTP_DYNAMIC_BUNDLES". It must point to your "Oauth2ResUpdateSite.nsf" database. Use a comma to separate multiple values if you already have another entry (for dom-spring for example).
Restart the http task (console command):
restart task http
Check that plugins are deployed :
tell http osgi ss oauth.resource
You should see something like this :
> tell http osgi ss oauth
[1C04:0002-1C08] 28/09/2017 14:27:39 Framework is launched.
[1C04:0002-1C08] 28/09/2017 14:27:39 id State Bundle
[1C04:0002-1C08] 28/09/2017 14:27:39 95 <<LAZY>> com.github.lhervier.domino.oauth.resource_1.0.0.qualifier
[1C04:0002-1C08] 28/09/2017 14:27:39 96 RESOLVED com.github.lhervier.domino.oauth.resource.external.expiringmap_0.5.8
As every dom-spring projects, oauth2-dom-res-server is waiting for Spring properties that can be injected using multiple means :
- From environment variables
- From notes.ini variables
- Or from a custom osgi plugin
The awaited properties are :
| Property | Description |
|---|---|
| oauth2.resource.checkTokenUrl | OAuth2 Token introspection endpoint |
| oauth2.resource.clientId | OAuth2 client Id |
| oauth2.resource.secret | OAuth2 client secret |
The token introspection endpoint depends on your Authroization Server.
The clientId and secret are used to authenticate your resource server with the OAuth2 Authorization Server when accessing the introspection endpoint.
Values for oauth2-dom-auth-server
Have a look at the documentation of oauth2-dom-auth-server project. Once your server is up and running, declare a new application :
- Open the oauth2.nsf database with a web browser
- Login as a user with the [AppsManager] role
- Add a new application :
- Enter a name
- Client type can be public or confidential
- Set "readers" to the list of users that will be able to log into this application
- Redirect uri: for testing purpose, enter "http://localhost/myapp"
When you will click save, you will obtain the client id and the secret.
Now, in order to test the values, get an access token : Point your browser to the oauth2 authorize endpoint
http://<your domino server>/oauth2.nsf/oauth2-server/authorize?client_id=<your client id>&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp
Your browser should be redirected to the non existing url "http://localhost/myapp", followed by "#access_token=". Extract this value, and keep it for testing.
The token introspection endpoint for oauth2-dom-auth-server is :
http://<your domino server>/oauth2.nsf/oauth2-server/checkToken
To check that you extracted the right values, you can use a Rest client like Postman to send a POST request to this URL :
- Add a "token" request parameter with the access token value extracted in the previous step. Use "x-www-form-urlencoded" format
- Add an authorization using Basic Authentication. Set the user as the client id, and the password as the secret.
You should get an answer saying that the token is valid (in the 'active' JSON attribute).
- Open the Google Cloud Developper Console
- Create a new project
- From the main menu (the icon in the upper left corner) go to "APIs And Services"
- Go to the "Credentials" page
- Click "create credential" / "OAuth client id"
- Select "Web application" client type :
- Enter a name for your credentials
- For testing purpose, enter "http://localhost/myapp" in the "Authorized redirect uris" field
- Click create
- A popin will show with the client id and the secret
Now, extract an access token by pointing your browser to the oauth2 authorization endpoint :
https://accounts.google.com/o/oauth2/v2/auth?client_id=<your client id>&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp&scope=profile
Your browser should be redirected to the non existing url "http://localhost/myapp", followed by "#access_token=". Extract this value, and keep it for testing.
The token introspection endpoint for Google Cloud is : https://www.googleapis.com/oauth2/v3/tokeninfo
Beware that this endpoint is not compliant to the RFC7662 ! The parameter have to be named "access_token" instead of "token", and you will not have an "active" attribute in the answer !
To check if you extracted the right values, you can use a Rest client like Postman to send a POST request to the URL :
- Set an "access_token" request parameter with the access token value extracted in the previous step. Use "x-www-form-urlencoded" format
- Add authorization using Basic Authentication. Set the user as the client id, and the password as the secret.
You should get a JSON answer with information from the token (like the expiration date in a "exp" attribute).
This will not work because Azure do not provide a token introspection endpoint. The access tokens provided by Azure are JWTs that you can verify using a RSA public key.
First, clone or download the source code from github into a local folder.
Refer to the dom-spring project page to donwload it.
- Go to File/Preferences menu, in the "Domino Designer" section, and check "Enable Eclipse plug-in install"
- Now, go to File/Application/Install menu.
- Select "Search for new features"
- Add a "Zip/jar location" and go find the zip that correspond to the dom-spring update site.
- Click Finish, and accept licences.
- Designer will ask to restart.
- Open Domino Designer
- Open the "package explorer" view, right click in the blank part, and select Import.
- In the "General" section, select "Existing projets into workspace"
- Click "Browse" and select the folder named "domino-osgi" in this project's sources.
- Select all projects and click "Import"
The code is now imported in your IBM Domino Designer. It should compile fine.
Open the file named site.xml in the "domino-osgi/com.github.lhervier.domino.oauth.resource.update" project, and click the "Build all" button.
Download the XPages SDK zip file from :
https://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20SDK%20for%20Eclipse%20RCP
Unzip the file to the folder of your choice. Then, in Eclipse, go to the menu "Help / Install new software".
In the dialog box, click the "add" button in from of the "Work with" combo :
- Name = XPages sdk
- Click the "Folder" button, and go find the folder named "org.openntf.xsp.sdk.updatesite" in the extracted zip file.
Select all features, accept licences, "Install anyway" when prompted to, and restart Eclipse.
Open Eclipse preferences, and go to the section "XPages SDK" :
- Enable using IBM DOMINO on this computer
- Enter the path to the notes.ini, the installation folder of your Domino Server, and the path to your data folder.
- Click "Automatically create JRE for domino"
- And "Apply".
This will create a new JRE Runtime, and a new Target platform. Select them :
- Go to the section "Java / Installed JREs", and select the newly created JRE (XPages Domino JRE)
- Go to the section "Plugins Development / Target platform", and select the newly created target platform (Domino Target).
- Menu Help / Install New Software
- Add an update site
- Go find the update site (the zip file) you juste downloaded
- Click next, finish, etc... until Eclipse ask to reboot.
In the package explorer, right click :
- Select "Import", then choose "General / Existing project into workspace".
- Go search for the folder where you cloned the sources
- And import the projects.
The code should compile fine.
Once the code is deployed, you will be able to generate the update site by opening the site.xml file of the "com.github.lhervier.domino.oauth.resource.update" project. Simply click the "Build all" button.
As the dom-spring plugins are not available at maven central, you must first install them manually. For this, follow the README.md file present in the dom-spring github website :
- Install "IBM Domino Update Site for Build Management", let's say in c:\UpdateSite
- Download dom-spring source code
- In the source folder run the maven install command : mvn install -Dnotes-platform=file:///c:/UpdateSite
Now that your local maven repository is initialized, generate the oauth2-dom-res-server update site. CD into the "domino-osgi" folder, and just type :
mvn install -Dnotes-platform=file:///c:/UpdateSite
The update site will be generated in
/domino-osgi/com.github.lhervier.domino.oauth.resource.update/target/com.github.lhervier.domino.oauth.resource.update-<version>.zip
Depending on the Authorization Server, you will have to declare a new OAuth2 application. This should give you the clientId and the secret.
The Authorization Server should also document the token introspection URL.
You have to install the dom-spring update site into your Designer. The update site is the same that you installed on your Domino Server :
- Go to File/Preferences menu, in the "Domino Designer" section, and check "Enable Eclipse plug-in install"
- Now, go to File/Application/Install menu.
- Select "Search for new features"
- Add a "Zip/jar location" and go find the zip that correspond to the dom-spring update site (the same file you use to install on your server).
- Click Finish, and accept licences.
- Designer will ask to restart.
You have to install the same update site that you deployed on your Domino Server :
- Go to File/Preferences menu, in the "Domino Designer" section, and check "Enable Eclipse plug-in install"
- Now, go to File/Application/Install menu.
- Select "Search for new features"
- Add a "Zip/jar location" and go find the zip that correspond to this project update site (the same file you use to install on your server).
- Click Finish, and accept licences.
- Designer will ask to restart.
Working with standard Eclipse requires a few more steps.
Download the XPages SDK zip file from :
https://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20SDK%20for%20Eclipse%20RCP
Unzip the file to the folder of your choice. Then, in Eclipse, go to the menu "Help / Install new software".
In the dialog box, click the "add" button in from of the "Work with" combo :
- Name = XPages sdk
- Click the "Folder" button, and go find the folder named "org.openntf.xsp.sdk.updatesite" in the extracted zip file.
Select all features, accept licences, "Install anyway" when prompted to, and restart Eclipse.
Open Eclipse preferences, and go to the section "XPages SDK" :
- Enable using IBM DOMINO on this computer
- Enter the path to the notes.ini, the installation folder of your Domino Server, and the path to your data folder.
- Click "Automatically create JRE for domino"
- And "Apply".
This will create a new JRE Runtime, and a new Target platform. Select them :
- Go to the section "Java / Installed JREs", and select the newly created JRE (XPages Domino JRE)
- Go to the section "Plugins Development / Target platform", and select the newly created target platform (Domino Target).
Once your environment is ready, you can install the update site.
- Menu Help / Install New Software
- Add an update site
- Go find the update site (the zip file) you just downloaded
- Click next, finish, etc... until Eclipse ask to reboot.
Once your environment is ready, you can install the update site.
- Menu Help / Install New Software
- Add an update site
- Go find the update site (the zip file) you just downloaded
- Click next, finish, etc... until Eclipse ask to reboot.
Rest services are implemented using Spring Rest, as described in the Domino Spring Project, but with little differences :
- Extend the BaseOauthResourceServlet instead of OsgiDispatcherServlet. This one will only allow requests à the root of the server context.
- Your Spring Configuration class will have to extend the provided "com.lhervier.github.domino.oauth.resource.BaseOauthResourceConfig" class. This will allow you to @Autowired a bean based on the "com.github.lhervier.domino.oauth.resource.BearerContext" class.
The BearerContext will give you access to :
- The description of the access token by using its getAccessToken() method.
- A Notes Session opened as a user whose name is in the "sub" property of the token. Use the getBearerSession() method to get it.
The "sample" folder contains a sample application that declares a simple Rest Service accessible via a bearer token. Once you have deployed the plugin, you can access the following URL :
http://dominoserver/resource-sample/apis/users?startsWith=X&limit=10
You will have to add a HTTP header "Authorization" that contains the "Bearer" keyword followed by your OAUTH2 access token.
The request will answer with a JSON object that reads the users from the ($VIMPeople) view of the names.nsf database (showing that user rights are OK). It will also return the current user name, and the authorized scopes.
To play with the code, simply import the projects present in the "sample" sub folder into Domino Designer.
- Test with Google Cloud (Only tested using oauth2-dom-auth-server)
- Implement decoding tokens as JWTs (to support ADFS)
- Make update site generation work with maven