[Article] Integrate your Social Identity with Enterprise Identity by Leveraging WSO2 Identity Server and WSO2 API Manager
- Gayan Gunawardana
- - WSO2
Introduction
Social media has become one of most essential parts of modern society. There are a lot of well-known social media sites such as Facebook, LinkedIn, Twitter, YouTube, MySpace, Flickr, WordPress and Blogger among many others. There are is also a high level of interest among businesses and enterprise applications for bring your own identity (BYOID) initiatives where social networking or digital identities are used for application login purposes.
A single user can have multiple user accounts in multiple identity providers. Account linking allows a user to login from one account and access resources that belong to all other associate accounts. Suppose you have a separate Gmail account and Windows account. Once you associate your Windows account with your Gmail account, you can provide your Gmail account credentials to access resources that belong to your Windows account.
So how can you get the necessary set of permissions to perform the required operations when using your social identity to authenticate yourself to business and enterprise applications. In other words, how do you find the roles corresponding to you (set of permissions represent a role). This is where account linking is essential. Your need to link your social account with your enterprise account. Once you have done this, the necessary authorization information can be retrieved from your enterprise account ID.
Applies to
| WSO2 Identity Server | Version 5.0.0 |
| WSO2 API Manager | Version 1.7.0 |
Contents
- New features in WSO2 Identity Server 5.0.0
- Sample use-case
- Architectural design and configurations
- Getting inbound authentication configuration from IS after creating an Oauth application in APIM
- Usage of local authenticator
- Multi-step authentication process
- Secure your API with WSO2 API Manager
- Sample XACML policy for role based access control
- Conclusion
- References
New features in WSO2 Identity Server 5.0.0
WSO2 Identity Server 5.0.0 has been released with more powerful features such as multi-step authentication and the ability to register external identity providers and link federated user accounts with a local user account1.
The new dashboard concept primarily supports the linking of your social account with your local account under the ‘Social Login’ gadget. If you don’t need a UI experience and prefer a program that can perform account linking, you can utilize ‘Admin Services’ rather that using the WSO2 IS dashboard. Your can also manage your user profile, add security question, revoke/update your password, manage your OpenID profile and view identity providers using the new WSO2 IS dashboard.
Sample use-case
Now see a real world use case. In this scenario, people who are under the hrAdmin role can access salary details of company emails via their Facebook login credentials.
Suppose you have simple non-secured backend service which returns the salary details of a list of employees;
Request
https://
Response
"employees":[
{"name":"Nuwan", "salary":"85000$"},
{"name":"Ruwan", "salary":"84000$"},
{"name":"John", "salary":"90000$"}
]
Now you need to secure this backend service using the following;
https://
Users who have the hrAdmin role can do the above API call with the access token they have obtained from their Facebook login.
Architectural design and configurations
Configurations in brief
- Configure WSO2 Identity Server as a key manager for WSO2 API Manager (APIM) for more information refer 2
- Configure Facebook as a federated authenticator in WSO2 Identity Server (IS).
Figure 01
- Register the service provider in WSO2 IS and add authentication step 01 for Facebook federated authenticator and authentication step 02 for local authenticator. For more information refer to the section on Multi-step authentication process.
- Link the Oauth application created by the APIM side with the IS service provider inbound authentication configuration. This will be explained more under the Getting inbound authentication configuration form IS after creating an Oauth application in APIM section.
Figure 02
.
Steps in brief
- Client Application sends the authorization request to the API manager authorization endpoint from the authorization code grant type or implicit grant type 3.
- The IS receives the request sent by client application via the APIM.
- The IS looks at the inbound authentication configuration and performs authentication step 01 with Facebook federated authenticator.
- The Facebook login page will be prompted to the end user and authenticated with Facebook IDP.
- The IS looks into inbound authentication configuration again and performs authentication step 02 with the local authenticator. The idea of the local authenticator is to associate your Facebook account with your local account. This will be discussed in detail under The usage of local authenticator section.
- If the grant type is implicit you will get the access token directly after completing the authentication process. If the grant type is authorization code you have to send a token request after getting the authorization code from the authorize request.
- Once you have the access token you can invoke the necessary APIs by setting the access token as the security header.
- The API authentication handler verifies the access token and identifies which access token the user belongs to.
- The entitlement mediator is the Policy Enforcement Point (PEP) where we intercept the request and look at it for role based permissions.
- If the result is “Permit” from the Policy Decision Point (PDP), the user will be entertained to invoke the API.
Getting inbound authentication configuration from IS after creating an Oauth application in APIM
Currently, even though you made the Oauth application from APIM side it is not visible to the IS side for inbound authentication configuration.
- If you are using MySQL as the database get SP and IDP tables into the MySQL environment. You can do it by performing the following configurations;
- Create a database with name idp_db
- Execute db script inside dbscripts/identity/application-mgt by pointing database idp_db
- Inside repository/conf/datasources/master-datasources.xml enter the following entry;
<datasource> <name>WSO2_IDP_DB</name> <description>The data source used for IDP and SP informations</description> <jndiConfig> <name>jdbc/WSO2_IDP_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/idp_db</url> <username>user</username> <password>xxxx</password> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource> - Enter the following entry in repository/conf/security/application-authentication.xml
<JDBCPersistenceManager> <DataSource> <Name>jdbc/WSO2_IDP_DB</Name> </DataSource> </JDBCPersistenceManager>
- Create an Oauth application from the API manager side. For the moment name it as MyApp.
Figure 03
Then you have to assign the application for a given API and go to Subscribe -> My Subscriptions and generate a consumer key and consumer secret
Figure 04
- Create a service provider for the IS side with the name MyApp
- Check your database tables
- IDN_OAUTH_CONSUMER_APPS
CONSUMER_KEY CONSUMER_SECRET USERNAME TENANT_ID APP_NAME AEw2i9A OwMcGh admin -1234 MyApp - SP_APP table
ID TENANT_ID APP_NAME USER_STORE 1 -1234 MyApp PRIMARY - Using the above two table you can fill in the necessary fields in the below P_INBOUND_AUTH table
ID TENANT_ID INBOUND_AUTH_KEY INBOUND_AUTH_TYPE PROP_NAME PROP_VALUE APP_ID 1 -1234 AEw2i9A oauth2 oauthConsumerSecret OwMcGh 1
After following the above steps you can view inbound authentication configurations from the service provider registered in the IS side.
Figure 05
- IDN_OAUTH_CONSUMER_APPS
Usage of local authenticator
Here the idea of the local authenticator is to link your social account with your local account in the identity server. In order to do this you have to give the credentials for the login page prompted by the identity server. Your will be prompted for your credentials only on your very first login. Thereafter your can seamlessly login using just your social account since the accounts are now associated. You can find the source code of the local authenticator from here.
Alternatively you can achieve account linking through the identity server dashboard but you have to go to different locations and login with your local account and then associate it with your social account.
Figure 06
Click on ‘Social Login’ and then associate social login. This sample shows how to associate the local account admin with the Facebook social account.
Figure 07
Multi-step authentication process
As mentioned in the beginning one of the most powerful features that came out with WSO2 Identity Server 5.0.0 is the multi-step authentication process where you have flexible authentication options. Now lets see how we can utilize the multi-step authentication process for the given use case.
Figure 08
Above you can see under ‘Local & Outbound Authentication Configuration’ the option ‘Advanced Configuration’ has been selected. This means that you can have a combination of local authenticators and federated authenticators. Also please note that “Assert identity using mapped local subject identifier” has been ticked. This means that the identity of the local account is used on behalf of the federate account if the federated account maps to any local account.
Figure 09
Authentication step configuration step 1
Select Facebook under ‘Federated Authenticators’ and leave the ‘Local Authenticators’ empty.
Authentication step configuration step 2
Select assoc-account under ‘Local Authenticator’ and leave the ‘Federated Authenticators’ empty.
Since you want to use the local account identity after authentication step 2 you should tick ‘Use subject identifier’ and ‘Use attribute from this step’.
Secure your API with WSO2 API Manager
Once you have created an API through the publisher, corresponding synapse configurations will be deployed to <apim_home>/repository/deployment/server/synapse-configs/default/api with name admin--hrinfo_v1.0.0.xml. Assume that the “hrinfo” API was created by admin. Now you need to apply role based permission for the newly created API. WSO2 APIM contains an entitlement mediator which acts as a PEP. Your can use this to intercept the request and apply role based permissions. In order to engage the entitlement mediator with the newly created API follow the below instructions.
Open admin--hrinfo_v1.0.0.xml and enter the entitlementService element in the beginning of inSequence for the entitlement mediator;
<?xml version="1.0" encoding="UTF-8"?><api xmlns="http://ws.apache.org/ns/synapse" name="admin--test" context="/hrinfo" version="1.0.0" version-type="url">
<resource methods="POST GET OPTIONS DELETE PUT" url-mapping="/*">
<inSequence>
<entitlementService xmlns="http://ws.apache.org/ns/synapse" remoteServiceUrl="https://localhost:9443/services" remoteServiceUserName="admin" remoteServicePassword="admin" callbackClass="org.wso2.sample.handlers.entitlement.APIEntitlementCallbackHandler"/>
<property name="POST_TO_URI" value="true" scope="axis2"/>
<filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
<then>
<send>
<endpoint name="admin--hrinfo_APIproductionEndpoint_0">
<http uri-template="https://127.0.0.1:9764/hr/">
You can find the source code for APIEntitlementCallbackHandler here. If you need more explanation about how a request can be intercepted and how to evaluate the XACML policy please refer to this article.
Sample XACML policy for role based access control
According to the given use case security policy would be to allow the HTTP GET request (Action) where the url parameter is info=salary (Resource) and the role is “hrAdmin” (Subject).
You can create an XACML policy using a simple policy editor.
Figure 09
<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicyId="hrSalaryPolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" Version="1.0">
<Description>only hrAdmin can see salary information of others</Description>
<Target/>
<Rule Effect="Permit" RuleId="Rule-1">
<Target>
<AnyOf>
<AllOf>
<Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<AttributeValue DataType="https://www.w3.org/2001/XMLSchema#string">salary</AttributeValue>
<AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource" DataType="https://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
</Match>
</AllOf>
</AnyOf>
<AnyOf>
<AllOf>
<Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<AttributeValue DataType="https://www.w3.org/2001/XMLSchema#string">GET</AttributeValue>
<AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="https://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
</Match>
</AllOf>
</AnyOf>
</Target>
<Condition>
<Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:any-of">
<Function FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-equal"/>
<AttributeValue DataType="https://www.w3.org/2001/XMLSchema#string">hrAdmin</AttributeValue>
<AttributeDesignator AttributeId="https://wso2.org/claims/role" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="https://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
</Apply>
</Condition>
</Rule>
<Rule Effect="Deny" RuleId="Deny-Rule"/>
</Policy>
Conclusion
In this article, we discussed how to extend the authentication capabilities of WSO2 API Manager with the power of WSO2 Identity Server 5.0.0. Once you link your social account with your enterprise account you can perform any action authorized for your enterprise account by logging in with just your social account. Your social account will be the simplest and easiest point of authentication where multiple accounts are linked together.
References
- https://wso2.com/products/identity-server/
- https://docs.wso2.com/display/AM210/Configuring+WSO2+Identity+Server+as+a+Key+Manager
- https://docs.wso2.com/display/AM180/Token+API
- https://docs.wso2.com/display/AM180/Quick+Start+Guide
- https://github.com/GayanM/role-based-authorization-artifacts/tree/master/org.wso2.carbon.identity.application.authenticator.assoc.account
- https://github.com/GayanM/role-based-authorization-artifacts/tree/master/entitlement
- https://wso2.com/library/articles/2014/02/use-of-wso2-api-manager-to-validate-fine-grained-policy-decisions-using-xacml/