Apr 20, 2020
Setting up Wekan with Docker, OAuth2 and Oracle Identity Cloud Service
Wekan
Wekan is an open-source kanban board which allows a card-based task and to-do management. It is an ideal solution if you cannot make use of Cloud based solutions like Trello due to, for example, corporate information security or data locality policies. In those kinds of situations you might want to run Wekan on a local server in your data center. But you can chose to deploy Wekan on cloud platforms as well.
In this post we will assume Wekan is going to be installed on a local server with the following similar specs:
- 12 CPU
- 70 GB RAM
- 250 GB Disk
- Oracle Enterprise Linux 7.8
- Docker Engine version 19.03.8
- Git version 1.8.3.1
- Server only reachable on the local network
- Internet access through proxy
We’ll also assume you have basic knowledge of:
- Docker
- Linux/Mac OS
- Wekan
- OAuth2
- Oracle Identity Cloud Service
Installation and setup steps
The whole process is pretty straightforward and includes the following steps:
- Determine location for Wekan source files
- Getting the Wekan source files
- Initial deployment and test of Wekan on Docker
- Create initial (admin) user
- Setting up OAuth2 with Wekan
Determine location for Wekan source files
In this post we will use a users home directory to store the Wekan source files. Note that that the use must have rights to create, start and stop docker containers. Setup the user and cd into the users home directory.
Getting the source
An easy way to obtain the code is to use git clone. Go to the Wekan Github page and click the Clone or download button:
You will get a pop up, click the copy icon/button:
Go to your terminal, CD into the directory that you created and use the following command:
git clone https://github.com/wekan/wekan.gitThis will clone the source files into your users home directory. You can find them at ~/wekan in your users home folder.
Deploying Wekan on Docker
The Wekan sources on github provide a Docker-Compose.yml file that can be adapted easily to your requirements.
For a simple test it is sufficient to change/uncomment the following two parameters:
- - ROOT_URL=http://localhost
- - MAIL_URL=smtp://user:pass@mailserver.example.com:25/
Uncomment / change ROOT_URL, change this to the hostname of the server or localhost if running on local laptop/desktop.
Set the MAIL_URL to an SMTP server you have access to. If you do not set this, Wekan will complain during account setup, however it does not seem to block account creation.
After making and saving the changes, a simple:
docker-compose upwill start the Wekan app and the Wekan Database on your system. You can reach the application in a web browser on port 80, if you didn’t change the port mapping settings.
Verify if you get a login screen to check if everything went well:
Now that we know Wekan is working as expected, let’s move to the next part and set up a first user.
Create initial (admin) user
The first user created will be an admin user by default. On the login screen click Register. You will be redirected to the following screen:
Create a user by providing an username, valid e-mail address and password. Note that the e-mail address must belong to a valid user on the Identity Provider, in this case Oracle Identity Cloud Service. We will use this e-mail address to map an OICS user on the Wekan user.
If there is an issue with the e-mail server configuration, you will get an Internal server error message, but the account will still be created. Check the log files of the Docker container to see what is causing the issue.
After creating the first (admin) user, we can proceed to setup OAuth2. But first run:
docker-compose stopto stop the Wekan application and database before we make changes to Wekan configuration.
Setting up OAuth2
Oracle Identity Cloud service (OICS) is an next generation comprehensive security and identity platform that is cloud-native and designed to be an integral part of the enterprise security fabric, providing modern identity for modern applications.
It adheres to modern industry standards like OAuth2 and OpenID Connect. Oracle’s A-Team has provided an excellent more in depth article on this topic here.
Configuring OICS
Before we can setup OAuth2 in Wekan, we need to setup and configure our Wekan aplication instance as an “Client Application” in OICS. A client application, in OAuth2 terminology, is a trusted application in the OICS security domain and is allowed to interact with OICS Rest API’s to handle authentication and autorisation.
In the OICS console click “Applications”:
Click “Add”:
We are going to create a trusted application in OICS (OAuth regards this application as an application that can secure credentials), hence select confidential application:
Although you will be presented with many fields, we will only use the nescesary fields in this post. In the first screen, only fill in the name of the application — the name your application is known by in the OICS context. I will use Wekan Local Deployment, but it can anything you want:
Click Next and if all goes well you should see the following message:
On this screen select “Configure this application as a client now”:
and this will give us some additional fields to fill in. We only want/need to set the following values:
- Client Credentials: this will allow the Wekan application to identify itself to OICS with client ID and client secret
- Authorization Code: this setting will allow the Wekan application to trade an authorisation token for an access token to retrieve user profile details from the user stored in OICS
- Allow non-HTTPS URLs: we did not setup the Wekan application with an SSL certificate (for now — as this is an unsecure practise!)
- Redirect URL: this is the URL the user will be sent to after successful authentication. I am assuming the Wekan application is accessible on the local network by the hostname “wekan”. You might need to setup DNS on your network to accomplish this. The “_oauth/oidc” location is the Wekan application default for the redirect. Fill in your values and click Next:
On the third screen we can just leave the default values and click Next:
We do the same on the fourth screen, leave the default values and click Finish:
This will now give you a pop up with the Client ID and Client Secret:
Copy and paste the values, as we are going to need them later, and click Close.
Note: don’t save these credentials in an unsecure place. You might want to use a key vault to store this securely. Do not leave them unprotected on the files systems and/or source code repo.
Now the last step is to active the client application by clicking Activate:
You will get the following screen, just click Ok:
If all goes well you should see the following confirmation:
That’s it! Now we can move on to configuring our Wekan application. First we will get the end point information from OICS.
Getting the OICS endpoint information
As with all OAuth2 implementations we need to get some basic information from our Identity & Authorisation service, in this OICS. Every provider will give you an API endpoint that you can call to get the relevant meta-data of the service.
With OICS you can make an API call to:
http://{your OICS server}/.well-known/idcs-configurationwhere you replace {your OICS server} with the actual name of your OICS server name. It should look like the folllowing:
http://idcs-51de7830f1ae4fcdb013f6972b7c31da/.well-known/idcs-configurationYou can call this end point with a tool of your preference like Curl or Postman.
The response you will get, is very similar to the following (note: I have removed a lot of the output to show only relevant content in the context of this post):
{
"configuration": {
"version": "1",
"service_release_version": "0.1.0-dev-19.3.3-2003181629",
"myservices_endpoint": "https://myservices-cacct-5821ff0abc0d4081a90764a470bd9a7c.console.oraclecloud.com",
"IDCS_MASTER_REGION": "eu-frankfurt-idcs-2",
"IDCS_CREATED_IN_REGION": "eu-frankfurt-idcs-2",
"IDCS_CURRENT_REGION": "eu-frankfurt-idcs-2"
},...
"openid-configuration": {
"issuer": "https://identity.oraclecloud.com/",
"authorization_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/authorize",
"token_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/token",
"userinfo_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/userinfo",
"revocation_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/revoke",
"introspection_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/introspect",
"end_session_endpoint": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/userlogout",
"jwks_uri": "https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/admin/v1/SigningCert/jwk",...
}
}
What we will need from above is the authorization_endpoint, token_endpoint and and the userinfo_endpoint (marked in bold). Copy-paste the values and save them for the next part.
Configuring Wekan
Wekan provides out of the box support for OAuth2 and OpenID Connect. Again we will use the docker-compose file for our configuration. Although OICS is not documented in the docker-compose file, it is easy to set up by adding the following settings to our docker-compose file:
### OAUTH2 with Oracle Identity Cloud Service- OAUTH2_ENABLED=true# OAuth2 login style: popup or redirect - nore redirect is not implemted yet in Wekan,so you will get an popup- OAUTH2_LOGIN_STYLE=popup# Application ID captured during app registration in OICS:- OAUTH2_CLIENT_ID=51de7830f1ae4fcdb013f6972b7c31da# Secret key generated during app registration in OICS:- OAUTH2_SECRET=867fefc3-31b5-4d25-99fc-39924ce7f6f6# Get the following values from above described API call# For the server URL pick an endpoint URL and remove the part after ..cloud.com/- OAUTH2_SERVER_URL=https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/- OAUTH2_AUTH_ENDPOINT=/oauth2/v1/authorize- OAUTH2_USERINFO_ENDPOINT=https://idcs-51de7830f1ae4fcdb013f6972b7c31da.identity.oraclecloud.com/oauth2/v1/userinfo- OAUTH2_TOKEN_ENDPOINT=/oauth2/v1/token# The following values determine how the uses profile fields as stored in OICS are mapped on the Wekan user profile values# The claim name you want to map to the unique ID field:- OAUTH2_ID_MAP=email# The claim name you want to map to the username field:- OAUTH2_USERNAME_MAP=email# The claim name you want to map to the full name field:- OAUTH2_FULLNAME_MAP=name# Tthe claim name you want to map to the email field:- OAUTH2_EMAIL_MAP=email
Save the docker-compose file and run the following command to start Wekan with the new OAuth2 settings:
docker-compose upIf all goes well you should see the following updated login screen — the Sign In with Oidc button — in your browser:
Click the Sign In with Oidc button and you will get a popup screen:
At first login through OAuth2, OICS will ask you to allow the Wekan application to access your user profile and email data stored in OICS (note: I obscured the e-mail address in the top right of the image). Click Allow to proceed and you will be presented the OICS login screen:
Now use your accounts username and password to login. After succesful login you will have access to Wekan:
Congratulations, you now have an OAuth2 enabled Wekan deployment!
Next Steps
Obviously you don’t want to allow non HTTPS connections to your Wekan deployment. You can achieve this by setting up Wekan with SSL and an NGINX reverse proxy. I will describe how to do that in a next post.
In the meantime leave your questions and feedback below.
