This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Service Provider Configurations used with APIs
- Former user (Deleted)
- Former user (Deleted)
- Former user (Deleted)
This section guides you through the configurations you can include in a service provider application. See Calling Admin Services to enable the admin service.
Configuring SAML2 web SSO
Permission Level: /permission/admin/manage
To add a Service Provider with SAML2 Web SSO capability, you have to first add SAML2 Web SSO configuration. This is done through the IdentitySAMLSSOConfigService exposed at https://<IS_HOST>:<IS_PORT>/services/IdentitySAMLSSOConfigService?wsdl. Replace the tag <IS_HOST>:<IS_PORT> with the relevant host and port number, for example, https://localhost:9443/services/IdentitySAMLSSOConfigService?wsdl.
Input parameters
| Parameter | Type | Description |
|---|---|---|
| issuer | String | Specify the Issuer. This is the <saml:Issuer> element that contains the unique identifier of the service provider. This is also the issuer value specified in the SAML Authentication Request issued by the service provider. When configuring single-sign-on across Carbon servers, ensure that this value is equal to the ServiceProviderID value mentioned in the <IS_HOME>/repository/conf/security/authenticators.xml file of the relying party Carbon server. |
| assertionConsumerUrls | String | Specify the Assertion Consumer URLs. This is the URL to which the browser should be redirected to after the authentication is successful. This is the Assertion Consumer Service (ACS) URL of the service provider. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed and SAML2 request contains the ACS URL, the Identity Server will honor the ACS URL of the SAML2 request. It should have this format: https://(host-name):(port)/acs. You can add multiple assertion consumer URLs by repeating assertionConsumerUrls element. |
| defaultAssertionConsumerUrl | String | Since there can be multiple assertion consumer URLs, you must define a Default Assertion Consumer URL in case you are unable to retrieve it from the authentication request. Tip: In a service provider initiated single sign-on setup, the following needs to be considered.
In an identity provider initiated single sign-on setup, the following needs to be considered.
|
| nameIDFormat | String | Specify the NameID format. This defines the name identifier formats supported by the identity provider. The service provider and identity provider usually communicate with each other regarding a specific subject. That subject should be identified through a Name-Identifier (NameID) , which should be in some format so that It is easy for the other party to identify it based on the format. Name identifiers are used to provide information regarding a user. About NameID formats For SSO interactions, you can use the following types of NameID formats.
This specifies the name identifier format that the Identity Server wants to receive in the subject of an assertion from a particular identity provider. The following is the default format used by the identity provider. |
| certAlias | String | This is used to validate the signature of SAML2 requests and is used to generate encryption. Basically, the service provider’s certificate must be mentioned here. Note that this can also be the Identity Server tenant's public certificate in a scenario where you are doing a tenant-specific configuration. |
| signingAlgorithmURI | String | Specifies the ‘SignatureMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the |
| digestAlgorithmURI | String | Specifies the ‘DigestMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the |
| doSignResponse | Boolean | Set true to sign the SAML2 Responses returned after the authentication process. |
| doValidateSignatureInRequests | Boolean | Set true to specifies whether the identity provider must validate the signature of the SAML2 authentication request and the SAML2 logout request that is sent by the service provider. |
| doEnableEncryptedAssertion | Boolean | Set true if you wish to encrypt the assertion. |
| doSignAssertions | Boolean | Set this value to 'TRUE' or keep the value as empty since a valid assertion should be signed. |
| doSingleLogout | Boolean | Set true if you want to terminate all sessions once the user signs out from one service provider. If single logout is enabled, the identity provider sends logout requests to all service providers. Basically, the identity provider acts according to the single logout profile. If the service provider supports a different URL for logout, you need to specify them using sloResponseURL and sloRequestURL parameters. These URLs indicate where the request and response should go to. If you do not specify this URL, the identity provider uses the Assertion Consumer Service (ACS) URL. |
| enableAttributeProfile | Boolean | The Identity Server provides support for a basic attribute profile where the identity provider can include the user’s attributes in the SAML Assertions as part of the attribute statement. Ste true to enable this profile. If you set true to enableAttributesByDefault parameter, the identity provider always includes the attribute values related to the requested claims in the SAML attribute statement. |
| requestedAudiences | String | You can specify the audiences using this parameter. |
| requestedRecipients | String | You can specify the recipients using this parameter. |
| idPInitSSOEnabled | Boolean | Set true to enable IdP initiated SSO profile for the service provider. |
| idPInitSLOEnabled | Boolean | Set true to enable IdP initiated SLO profile for the service provider. |
| assertionQueryRequestProfileEnabled | Boolean | Set true to enable Assertion Query Request Profile to query assertions that are persisted to the database when you log in to the service provider application. For more information, see Querying SAML Assertions. |
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd" xmlns:xsd1="http://dto.saml.sso.identity.carbon.wso2.org/xsd">
<soapenv:Header/>
<soapenv:Body>
<xsd:addRPServiceProvider>
<!--Optional:-->
<xsd:spDto>
<!--Zero or more repetitions:-->
<xsd1:assertionConsumerUrls>?</xsd1:assertionConsumerUrls>
<!--Optional:-->
<xsd1:assertionQueryRequestProfileEnabled>?</xsd1:assertionQueryRequestProfileEnabled>
<!--Optional:-->
<xsd1:attributeConsumingServiceIndex>?</xsd1:attributeConsumingServiceIndex>
<!--Optional:-->
<xsd1:certAlias>?</xsd1:certAlias>
<!--Optional:-->
<xsd1:defaultAssertionConsumerUrl>?</xsd1:defaultAssertionConsumerUrl>
<!--Optional:-->
<xsd1:digestAlgorithmURI>?</xsd1:digestAlgorithmURI>
<!--Optional:-->
<xsd1:doEnableEncryptedAssertion>?</xsd1:doEnableEncryptedAssertion>
<!--Optional:-->
<xsd1:doSignAssertions>?</xsd1:doSignAssertions>
<!--Optional:-->
<xsd1:doSignResponse>?</xsd1:doSignResponse>
<!--Optional:-->
<xsd1:doSingleLogout>?</xsd1:doSingleLogout>
<!--Optional:-->
<xsd1:doValidateSignatureInRequests>?</xsd1:doValidateSignatureInRequests>
<!--Optional:-->
<xsd1:enableAttributeProfile>?</xsd1:enableAttributeProfile>
<!--Optional:-->
<xsd1:enableAttributesByDefault>?</xsd1:enableAttributesByDefault>
<!--Optional:-->
<xsd1:idPInitSLOEnabled>?</xsd1:idPInitSLOEnabled>
<!--Optional:-->
<xsd1:idPInitSSOEnabled>?</xsd1:idPInitSSOEnabled>
<!--Zero or more repetitions:-->
<xsd1:idpInitSLOReturnToURLs>?</xsd1:idpInitSLOReturnToURLs>
<!--Optional:-->
<xsd1:issuer>?</xsd1:issuer>
<!--Optional:-->
<xsd1:nameIDFormat>?</xsd1:nameIDFormat>
<!--Optional:-->
<xsd1:nameIdClaimUri>?</xsd1:nameIdClaimUri>
<!--Zero or more repetitions:-->
<xsd1:requestedAudiences>?</xsd1:requestedAudiences>
<!--Zero or more repetitions:-->
<xsd1:requestedRecipients>?</xsd1:requestedRecipients>
<!--Optional:-->
<xsd1:signingAlgorithmURI>?</xsd1:signingAlgorithmURI>
<!--Optional:-->
<xsd1:sloRequestURL>?</xsd1:sloRequestURL>
<!--Optional:-->
<xsd1:sloResponseURL>?</xsd1:sloResponseURL>
</xsd:spDto>
</xsd:addRPServiceProvider>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:createApplicationResponse xmlns:ns="http://org.apache.axis2/xsd">
<ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
</ns:createApplicationResponse>
</soapenv:Body>
</soapenv:Envelope>
Once the SAML SSO configuration is added, the issuer details need to be included in inbound authentication configurations of the service provider.
Parameter | Type | Description |
|---|---|---|
inboundAuthKey | String | Specify the issuer here, which is the unique identifier of the service provider. This is also the issuer value specified in the SAML Authentication Request issued by the service provider. |
inboundAuthType | String | For SAML 2.0, authentication type should be ‘samlsso’ |
Property Name | Property Value |
|---|---|
attrConsumServiceIndex | This is the consumer service index. The service provider should send this in the SAML request to get attributes of the authenticated subject. |
<xsd1:inboundAuthenticationConfig>
<!--Zero or more repetitions:-->
<xsd1:inboundAuthenticationRequestConfigs>
<!--Optional:-->
<xsd1:inboundAuthKey>travelocity.com</xsd1:inboundAuthKey>
<!--Optional:-->
<xsd1:inboundAuthType>samlsso</xsd1:inboundAuthType>
<!--Zero or more repetitions:-->
<xsd1:properties>
<!--Optional:-->
<xsd1:name>attrConsumServiceIndex</xsd1:name>
<!--Optional:-->
<xsd1:value>202240762</xsd1:value>
</xsd1:properties>
</xsd1:inboundAuthenticationRequestConfigs>
</xsd1:inboundAuthenticationConfig>
Configuring OAuth/OpenID Connect
Permission Level: /admin/manage/identity
To add a Service Provider with OAuth capability, add an OAuth application through the OAuthAdminService exposed at https://<IS_HOST>:<IS_PORT>/services/OAuthAdminService?wsdl. Replace the tag <IS_HOST>:<IS_PORT> with the relevant host and port number, for example, https://localhost:9443/services/OAuthAdminService?wsdl.
Input parameters
| Parameter | Type | Description |
|---|---|---|
| OAuthVersion | String | Specify the Oauth version using this parameter. Accepted values are 'OAuth-1.0a' and 'OAuth-2.0'. If you set OAuth Version as OAuth-1.0a, there is no need to fill the grantTypes parameter. This is because this version of OAuth does not support grant types. |
| applicationName | String | Service provider name |
applicationAccessTokenExpiryTime | String | Specify the time the application access token needs to expire. The value needs to be specified in milliseconds. |
| callbackUrl | This is the exact location in the service provider's application where an access token would be sent. This is a required field and it is important to configure, as it is imperative that the service provider receives the access token. This is necessary for security purposes to ensure that the token is not compromised. Configure multiple callback URLs From IS 5.2.0 onwards, regex-based consumer URLs are supported when defining the callback URL. This enables you to configure multiple callback URLs for one application. To configure the callback URL to work for both of these URLs, set it using a regex pattern as follows: regexp=(https://((myapp\.com)|(testapp:8000))(/callback)) You must have the prefix 'regexp=' before your regex pattern. To define a normal URL, you can specify the callback URL without this prefix. | |
| grantTypes | String | |
Allowed Grant Types - The following are the grant types that are used to get the access token: | ||
| Code | Entering the username and password required at the service provider will result in a code being generated. This code can be used to obtain the access token. For more information on this grant type, see this Authorization Code specification. | |
| Implicit | This is similar to the code grant type, but instead of generating a code, this directly provides the access token. For more information on this grant type, see this Implicit Grant specification. | |
| Password | This authenticates the user using the password provided and the access token is provided. For more information on this grant type, see this Resource Owner Password Credentials Grant specification. | |
| Client Credential | This is the grant type for the client key and client secret. If these two items are provided correctly by the service provider, the access token is sent. For more information on this grant type, see this Client Credentials specification. | |
| Refresh Token | This will enable the user to obtain an access token by using the refresh token once the originally provided access token is used up. For more information on this grant type, see this Refresh Token specification. | |
| SAML | This uses SAML assertion to obtain the access token. For more information on this grant type, see this SAML2 Bearer specification. | |
| IWA-NTLM | This is similar to the password grant type, but it is specific to Microsoft Windows users. | |
| urn:ietf:params:oauth:grant-type:jwt-bearer | This is a custom grant type. It uses a JWT token to obtain the access token. For more information about this grant type, see this JWT specification. | |
| oauthConsumerKey | String | This the consumer key of the OAuth application. If you keep this empty, Identity server will generate a consumer key. |
| oauthConsumerSecret | String | This the consumer secret of the OAuth application. If you keep this empty, Identity server will generate a consumer secret. |
| pkceMandatory | Boolean | Set true if you are using the Code grant type. PKCE is a recommended security measure used to mitigate a code interception attack. See Mitigating Authorization Code Interception Attacks for more information. |
| pkceSupportPlain | Boolean | Set true if you are using PKCE. |
refreshTokenExpiryTime | String | Specify the time the refresh token needs to expire. The value needs to be specified in milliseconds. |
userAccessTokenExpiryTime | String | Specify the time the user's access token needs to expire. The value needs to be specified in milliseconds. |
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd" xmlns:xsd1="http://dto.oauth.identity.carbon.wso2.org/xsd">
<soapenv:Header/>
<soapenv:Body>
<xsd:registerOAuthApplicationData>
<!--Optional:-->
<xsd:application>
<!--Optional:-->
<xsd1:OAuthVersion>?</xsd1:OAuthVersion>
<!--Optional:-->
<xsd1:applicationAccessTokenExpiryTime>?</xsd1:applicationAccessTokenExpiryTime>
<!--Optional:-->
<xsd1:applicationName>?</xsd1:applicationName>
<!--Optional:-->
<xsd1:callbackUrl>?</xsd1:callbackUrl>
<!--Optional:-->
<xsd1:grantTypes>?</xsd1:grantTypes>
<!--Optional:-->
<xsd1:oauthConsumerKey>?</xsd1:oauthConsumerKey>
<!--Optional:-->
<xsd1:oauthConsumerSecret>?</xsd1:oauthConsumerSecret>
<!--Optional:-->
<xsd1:pkceMandatory>?</xsd1:pkceMandatory>
<!--Optional:-->
<xsd1:pkceSupportPlain>?</xsd1:pkceSupportPlain>
<!--Optional:-->
<xsd1:refreshTokenExpiryTime>?</xsd1:refreshTokenExpiryTime>
<!--Optional:-->
<xsd1:userAccessTokenExpiryTime>?</xsd1:userAccessTokenExpiryTime>
</xsd:application>
</xsd:registerOAuthApplicationData>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:registerOAuthApplicationDataResponse xmlns:ns="http://org.apache.axis2/xsd">
<ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
</ns:registerOAuthApplicationDataResponse>
</soapenv:Body>
</soapenv:Envelope>
Once OAuth application is created, you can retrieve the OAuth consumer key and OAuth consumer secret by calling getOAuthApplicationDataByAppName service method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd">
<soapenv:Header/>
<soapenv:Body>
<xsd:getOAuthApplicationDataByAppName>
<!--Optional:-->
<xsd:appName>playground</xsd:appName>
</xsd:getOAuthApplicationDataByAppName>
</soapenv:Body>
</soapenv:Envelope>
Once the OAuth configuration is added, the OAuth consumer key/secret details need to be included in inbound authentication configurations of the service provider.
Parameter | Type | Description |
|---|---|---|
inboundAuthKey | String | OAuth Client Key |
inboundAuthType | String | For OAuth, authentication type should be ‘oauth2' |
Property Name | Property Value |
|---|---|
oauthConsumerSecret | OAuth client secret |
<xsd1:inboundAuthenticationConfig>
<!--Zero or more repetitions:-->
<xsd1:inboundAuthenticationRequestConfigs>
<!--Optional:-->
<xsd1:inboundAuthKey>li6JMbjW6WDMKTWsRnGcjp5zcGhi</xsd1:inboundAuthKey>
<!--Optional:-->
<xsd1:inboundAuthType>oauth2</xsd1:inboundAuthType>
<!--Zero or more repetitions:-->
<xsd1:properties>
<!--Optional:-->
<xsd1:name>oauthConsumerSecret</xsd1:name>
<!--Optional:-->
<xsd1:value>NMB3EAfxh4YvSTqbb3iMkongAHjW</xsd1:value>
</xsd1:properties>
</xsd1:inboundAuthenticationRequestConfigs>
</xsd1:inboundAuthenticationConfig>
Configuring WS-Trust Security Token service
Permission Level: /admin/manage/identity
To configure a service provider with the WS-Trust Security Token Service (STS), add a trusted service through the STSAdminService exposed at https://<IS_HOST>:<IS_PORT>/services/STSAdminService?wsdl. Replace the tag <IS_HOST>:<IS_PORT> with the relevant host and port number, for example, https://localhost:9443/services/STSAdminService?wsdl.
Input parameters
| Parameter | Type | Description |
|---|---|---|
| serviceAddress | String | Specify the endpoint address or the trusted relying party. |
| certAlias | String | Specify the certificate alias of the imported public certificate of the trusted relying party. |
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.sts.security.carbon.wso2.org">
<soapenv:Header/>
<soapenv:Body>
<ser:addTrustedService>
<!--Optional:-->
<ser:serviceAddress>?</ser:serviceAddress>
<!--Optional:-->
<ser:certAlias>?</ser:certAlias>
</ser:addTrustedService>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:addTrustedServiceResponse xmlns:ns="http://service.sts.security.carbon.wso2.org">
<ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
</ns:addTrustedServiceResponse>
</soapenv:Body>
</soapenv:Envelope>
Once the trusted service is registered, the service address needs to be included in inbound authentication configurations of the service provider.
Parameter | Type | Description |
|---|---|---|
inboundAuthKey | String | The endpoint address of the trusted relying party. |
inboundAuthType | String | For WS-Trust Security Token Service, the authentication type should be ‘wstrust’ |
<xsd1:inboundAuthenticationConfig>
<!--Zero or more repetitions:-->
<xsd1:inboundAuthenticationRequestConfigs>
<!--Optional:-->
<xsd1:inboundAuthKey>https://www.example.com/sts</xsd1:inboundAuthKey>
<!--Optional:-->
<xsd1:inboundAuthType>wstrust</xsd1:inboundAuthType>
</xsd1:inboundAuthenticationRequestConfigs>
</xsd1:inboundAuthenticationConfig>
Configuring WS-Federation (passive)
To configure a service provider with the WS-Federation (passive), you only need to include following parameters in inbound authentication configurations of the service provider.
Parameter | Type | Description |
|---|---|---|
| String | Passive STS realm identifier |
| String | For Passive STS configuration, the authentication type should be ‘passivests’. |
passiveSTSWReply | String | Provide the URL of the web app. For example: https://localhost:8080/PassiveSTSSampleApp/index.jsp |
<xsd1:inboundAuthenticationConfig>
<!--Zero or more repetitions:-->
<xsd1:inboundAuthenticationRequestConfigs>
<!--Optional:-->
<xsd1:inboundAuthKey>TestSP</xsd1:inboundAuthKey>
<!--Optional:-->
<xsd1:inboundAuthType>passivests</xsd1:inboundAuthType>
<xsd1:properties>
<xsd1:name>passiveSTSWReply</name>
<xsd1:value>{url}</value>
</xsd1:properties>
</xsd1:inboundAuthenticationRequestConfigs>
</xsd1:inboundAuthenticationConfig>
- See Using APIs for key APIs relevant for Developers
- See Permissions Required to Invoke Admin Services for a list of the operations that can be performed with different permission levels
- The following article guides you through transforming existing SOAP-based services into REST services in WSO2 Identity Server: Exposing WSO2 Identity Server Admin Services the REST Way.