67 lines
3.4 KiB
Plaintext
67 lines
3.4 KiB
Plaintext
== OAuth
|
|
|
|
Fineract has a (basic) OAuth2 support based on Spring Boot Security. Here's how to use it:
|
|
|
|
=== Build
|
|
|
|
You must re-build the distribution JAR (or WAR) using the special `-Psecurity=oauth` flag:
|
|
|
|
----
|
|
./gradlew bootRun -Psecurity=oauth
|
|
----
|
|
|
|
Downloads from https://fineract.apache.org, or using e.g. the https://hub.docker.com/r/apache/fineract container image, or on https://www.fineract.dev, this will not work, because they have not been built using this flag.
|
|
|
|
Previous versions of Fineract included a built-in authorisation server for issuing OAuth tokens. However, as the spring-security-oauth2 package was deprecated and replaced by built-in OAuth support in Spring Security, this is no longer supported as part of the package. Instead, you need to run a separate OAuth authorization server (e.g. https://github.com/spring-projects/spring-authorization-server) or use a 3rd-party OAuth authorization provider (https://en.wikipedia.org/wiki/List_of_OAuth_providers)
|
|
|
|
This instruction describes how to get Fineract OAuth working with a Keycloak (http://keycloak.org) based authentication provider running in a Docker container. The steps required for other OAuth providers will be similar.
|
|
|
|
=== Set up Keycloak
|
|
|
|
1. From terminal, run: 'docker run -p 9000:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:15.0.2'
|
|
1. Go to URL 'http://localhost:9000/auth/admin' and login with admin/admin
|
|
1. Hover your mouse over text "Master" and click on "Add realm"
|
|
1. Enter name "fineract" for your realm
|
|
1. Click on tab "Users" on the left, then "Add user" and create user with username "mifos"
|
|
1. Click on tab "Credentials" at the top, and set password to "password", turning "temporary" setting to off
|
|
1. Click on tab "Clients" on the left, and create client with ID 'community-app'
|
|
1. In settings tab, set 'access-type' to 'confidential' and enter 'localhost' in the valid redirect URIs.
|
|
1. In credentials tab, copy string in field 'secret' as this will be needed in the step to request the access token
|
|
|
|
Finally we need to change Keycloak configuration so that it uses the username as a subject of the token:
|
|
|
|
1. Choose client 'community-app' in the tab 'Clients'
|
|
1. Go to tab 'Mappers' and click on 'Create'
|
|
1. Enter 'usernameInSub' as 'Name'
|
|
1. Choose mapper type 'User Property'
|
|
1. Enter 'username' into the field 'Property' and 'sub' into the field 'Token Claim Name'. Choose 'String' as 'Claim JSON Type'
|
|
|
|
You are now ready to test out OAuth:
|
|
|
|
=== Retrieve an access token from Keycloak
|
|
|
|
----
|
|
curl --location --request POST \
|
|
'http://localhost:9000/auth/realms/fineract/protocol/openid-connect/token' \
|
|
--header 'Content-Type: application/x-www-form-urlencoded' \
|
|
--data-urlencode 'username=mifos' \
|
|
--data-urlencode 'password=password' \
|
|
--data-urlencode 'client_id=community-app' \
|
|
--data-urlencode 'grant_type=password' \
|
|
--data-urlencode 'client_secret=<enter the client secret from credentials tab>'
|
|
----
|
|
|
|
The reply should contain a field 'access_token'. Copy the field's value and use it in the API call below:
|
|
|
|
=== Invoke APIs and pass `Authorization: bearer ...` header
|
|
|
|
----
|
|
curl --location --request GET \
|
|
'https://localhost:8443/fineract-provider/api/v1/offices' \
|
|
--header 'Fineract-Platform-TenantId: default' \
|
|
--header 'Authorization: bearer <enter the value of the access_token field>'
|
|
|
|
----
|
|
|
|
NOTE: See also https://demo.fineract.dev/fineract-provider/api-docs/apiLive.htm#authentication_oauth
|