Goal : Configure OAuth2 Authentication for Magic xpi RESTful API Service using KeyCloak Issuer
Prerequisites :
- Access to a Keycloak server https://www.keycloak.org/
- Apache tomcat
- Magic xpi
- Postman
1/ keyCloak Server Installation
Download and unzip keycloak server
install java version “17.0.11” 2024-04-16 LTS
Start Keycloak server (Dev environment) : kc start-dev
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/1-1024x576.png)
Browse : http://localhost:8080 and create Admin user
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/2-1024x576.png)
2/ Keycloak settings
Create Realm for Magic xpi
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/4-1024x576.png)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/5-1024x576.png)
Create Magic xpi Client
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/6-1024x576.png)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateClient-1024x496.png)
3/ Enter an URL redirection to Magic xpi RESTFul API
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateClient_2-1024x657.png)
Save the Client Secret
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateClient_3-1024x551.png)
4/ Create a Client Scope (magicxpiscope)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateScope1-1024x610.png)
Create 2 mapper (UserProperty (boolean) and UserAttribute (custom atrribute)) (Add mapper By Configuration)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateScope2.png)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateScope3-1024x738.png)
4/ Add the client scope “magicxpiscope” to the client
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/CreateScope4-1024x510.png)
4/ Deploy Magic xpi Tomcat requester (Magic xpi – RESTful API Provider Installation Instructions.pdf)
Copy the file xpiREST.war from<Magic xpi installation>\Runtime\addon_connectors\RESTfulAPI\servicefiles to <Magic xpi installation>\Runtime\apache-tomcat\webapps
We will use the Magic xpi Embedded Apache Tomcat (<Magic xpi installation>\Runtime\apache-tomcat).
Change the Apache Tomcat port to 6443 in the server.xml file and start the server
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/apache1-1024x617.png)
after starting the Apache server (<xpi installation>\Runtime\apache-tomcat\bin\startup.bat), xpiREST and rest-services will appear.
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/apache2.png)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/apache3.png)
5/ Create a Magic xpi project including a RESTFul Service
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/xpi1-1024x442.png)
Define 2 methods
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/xpi2-1024x349.png)
Under <xpi project>\RESTful API\<ServiceNameFolder>. (ex: C:\MSE\Magicxpi414\Runtime\projects\OAuth2_Keycloak\OAuth2_Keycloak\RESTful API\MyRESTfulAPI)
you will find the Service Definition File (<Project Name>_<Service Name>_serviceDefinition.xml) (C:\MSE\Magicxpi414\Runtime\projects\OAuth2_Keycloak\OAuth2_Keycloak\RESTful API\MyRESTfulAPI\OAuth2_Keycloak_MyRESTfulAPI_serviceDefinition.xml)
Add the OAuth2 Issuer (http://localhost:8080/realms/Magicxpi) and the security role => client scope for each method
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/Servicedef1-1024x406.png)
6/ Copy the Service Definition file from <xpi project>\RESTful API\<ServiceNameFolder> to <Magic xpi installation>\Runtime\apache-tomcat\rest-services
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/xpi4.png)
7/ Test using Postman
Make a POST on http://localhost:8080/realms/Magicxpi/protocol/openid-connect/token with these credentials with scope set to openid email address profile magicxpiscope
Check in the response that you get the clientscope that you want
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/postman1-1-1024x672.png)
In the response you will get the “access_token” and the “refresh_token” , if you want to test a call to the Magic xpi RESTFUl service, you can use access_token in the authorization header
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/Postman2-1024x421.png)
(*) You got Status 201 because in the Magic xpi Flow, i put 201 in C.UserCode
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/xpi6-1024x446.png)
(**) if you set a wrong role in the service definition file, you get a 403 Forbidden
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/postman3.png)
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/06/postman2-1024x384.png)
(***) If you pass a wrong Bearer token or if the token is expired then you get 401 Unauthorized
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/Postman3-1024x431.png)
8/ By default, the Access token expired after 5min, you can change this setting in the KeyCloak console
![](https://france.magicsoftware.com/blog/wp-content/uploads/2024/05/14-1024x588.png)