Page History
...
The API Manager comprises the following high-level components:
API Publisher
Provides an end user, collaborative Web interface for API providers to publish APIs, share documentation, provision API keys, and gather feedback on API features, quality and usage. For API Publisher use cases, see API Developer Tutorials.
API Store
...
API Gateway
A runtime, backend component (an API proxy) developed using WSO2 ESB. API Gateway secures, protects, manages, and API development is usually done by someone who understands the technical aspects of the API, interfaces, documentation, versions etc., while API management is typically carried out by someone who understands the business aspects of the APIs. In most business environments, API development is a responsibility that is distinct from API publication and management.
WSO2 API Manager provides a simple Web interface called WSO2 API Publisher for API development and management. It is a structured GUI designed for API creators to develop, document, scale and version APIs, while also facilitating more API management-related tasks such as publishing API, monetization, analyzing statistics, and promoting.
The API Publisher URL is https://<YourHostName>:9443/publisher and it is accessible on HTTPS only. The default credentials are admin/admin.
The diagram below shows the common lifecycle activities of an API developer/manager:
API Store
The API Store Web application provides a collaborative interface for API publishers to host and advertise their APIs and for API consumers to self register, discover, evaluate, subscribe to and use secured, protected, authenticated APIs.
The API Store URL is https://<YourHostName>:9443/store and it is accessible on HTTPS only. The default credentials are admin/admin.
The diagram below shows common API consumer lifecycle activities:
API Gateway
A runtime, backend component (an API proxy) developed using WSO2 ESB. API Gateway secures, protects, manages, and scales API calls. It intercepts API requests, applies policies such as throttling and security using handlers and manages API statistics. Upon validation of a policy, the Gateway passes Web service calls to the actual backend. If the service call is a token request, the Gateway passes it directly to the Key Manager.
When the API Manager is running, you can access the Gateway using the URL https://localhost:9443/carbon. You integrate a monitoring and statistics component to the API Manager without any additional configuration effort. This monitoring component integrates with WSO2 Business Activity Monitor, which can be deployed separately to analyze events. For more information, see Publishing API Runtime Statistics.
...
The components are depicted in the diagram below:
...
Users and roles
...
You can define throttling in the API, application and resource levels. The final request limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together.
Example: Lets say two users subscribed to an API using the Gold subscription, which allows 20 requests per minute. They both use the application App1 for this subscription, which again has a throttling tier set to 20 requests per minute. All resource level throttling tiers are unlimited. In this scenario, although both users are eligible for 20 requests per minute access to the API, each ideally has a limit of only 10 requests per minute. This is due to the application-level limitation of 20 requests per minute.
...
Let's take a look at the different levels of throttling:
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
...
Application-level throttling
APIApplication-level throttling tiers are defined when managing APIs using the API Publisher portal. The UI looks as follows:
After API-level throttling tiers are set and the API is published, at subscription time, the consumers of the API can log in to the API Store and select which tier they are interested in as follows:
According to the tiers the subscriber selects, s/he is granted a maximum number of requests to the API. The default tiers are as follows:
- Bronze: 1 request per minute
- Silver: 5 requests per minute
- Gold: 20 requests per minute
- Unlimited: Allows unlimited access (you can disable the Unlimited tier by editing the
<TierManagement>node of the<APIM_HOME>/repository/conf/api-manager.xmlfile)
Setting tier permissions: Users with Manage Tiers permission can set role-based permissions to API-level access throttling tiers. This is done using the Tier Permissions menu in the API Publisher as shown below. For each tier, you can specify a comma-separated list of roles and either Allow or Deny access to the list.
A subscriber logged into the API Store can consume APIs using a specific tier only if s/he is assigned to a role that is allowed access. In the API Store, the subscriber sees a list of tiers that is filtered based on the subscriber's role. Only the ALLOWED roles appear here. By default, all tiers are allowed to everyone.
Application-level throttling
Application-level throttling tiers are defined at the time an application is created in the API Store as shown below:
An application is a logical collection of one or more APIs and is required to subscribe to an API. Applications allow you to use a single access token to invoke a collection of APIs and to subscribe to one API multiple times with different SLA levels.
An application is available to a consumer at different levels of service. For example, if you have infrastructure limitations in facilitating more than a certain number of requests to an application at a time, the throttling tiers can be set accordingly so that the application can have a maximum number of requests within a defined time. The default throttling levels are are as follows:
- Bronze: 1 request per minute
- Silver: 5 requests per minute
- Gold: 20 requests per minute
- Unlimited: Unlimited access. The Default Application, which is provided out of the box has Unlimited tier set. You have the option to set it to a restricted limit.
Resource-level throttling
An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API. Resource-level throttling tiers are set to HTTP verbs of an API's resources when Managing APIs using the API Publisher portal as shown below:
The default throttling levels are Gold, bronze, silver and unlimited, as explained in the previous sections.
When a subscriber views an API using the API Store, s/he can see the resource-level throttling tiers using the Throttle Info tab as follows:
Subscribers are not allowed to change these throttling tiers. They are simply notified of the limitations.
IP-level throttling
In IP-based throttling, you can limit the number of requests sent by a client IP (e.g., 10 calls from single client).
...
Navigate to the tiers.xml file in the registry location /_system/governance/apimgt/applicationdata.
Add your policy. For example, the throttling policy shown below allows only 1 API call per minute for a client from 10.1.1.1 and 2 calls per minute for a client from any other IP address.
...
| language | xml |
|---|
...
at the time an application is created in the API Store as shown below:
An application is a logical collection of one or more APIs and is required to subscribe to an API. Applications allow you to use a single access token to invoke a collection of APIs and to subscribe to one API multiple times with different SLA levels.
An application is available to a consumer at different levels of service. For example, if you have infrastructure limitations in facilitating more than a certain number of requests to an application at a time, the throttling tiers can be set accordingly so that the application can have a maximum number of requests within a defined time. The default throttling levels are are as follows:
- Bronze: 1 request per minute
- Silver: 5 requests per minute
- Gold: 20 requests per minute
- Unlimited: Unlimited access. The Default Application, which is provided out of the box has Unlimited tier set. You have the option to set it to a restricted limit.
Resource-level throttling
An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API. Resource-level throttling tiers are set to HTTP verbs of an API's resources when Managing APIs using the API Publisher portal as shown below:
The default throttling levels are Gold, bronze, silver and unlimited, as explained in the previous sections.
When a subscriber views an API using the API Store, s/he can see the resource-level throttling tiers using the Throttle Info tab as follows:
Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.
...
Subscribers are not allowed to change these throttling tiers. They are simply notified of the limitations.
API-level throttling
API-level throttling tiers are defined when managing APIs using the API Publisher portal. The UI looks as follows:
After API-level throttling tiers are set and the API is published, at subscription time, the consumers of the API can log in to the API Store and select which tier they are interested in as follows:
According to the tiers the subscriber selects, s/he is granted a maximum number of requests to the API. The default tiers are as follows:
- Bronze: 1 request per minute
- Silver: 5 requests per minute
- Gold: 20 requests per minute
- Unlimited: Allows unlimited access (you can disable the Unlimited tier by editing the
<TierManagement>node of the<APIM_HOME>/repository/conf/api-manager.xmlfile)
Setting tier permissions: Users with Manage Tiers permission can set role-based permissions to API-level access throttling tiers. This is done using the Tier Permissions menu in the API Publisher as shown below. For each tier, you can specify a comma-separated list of roles and either Allow or Deny access to the list.
A subscriber logged into the API Store can consume APIs using a specific tier only if s/he is assigned to a role that is allowed access. In the API Store, the subscriber sees a list of tiers that is filtered based on the subscriber's role. Only the ALLOWED roles appear here. By default, all tiers are allowed to everyone.
IP-level throttling
In IP-based throttling, you can limit the number of requests sent by a client IP (e.g., 10 calls from single client).
- Log in to the management console and click the Resources -> Browse menu.
Navigate to the
tiers.xmlfile in the registry location/_system/governance/apimgt/applicationdata.
Add your policy. For example, the throttling policy shown below allows only 1 API call per minute for a client from 10.1.1.1 and 2 calls per minute for a client from any other IP address.
Code Block language xml <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle"> <throttle:MediatorThrottleAssertion> <wsp:Policy> <throttle:ID throttle:type="IP">10.1.1.1</throttle:ID> <wsp:Policy> <throttle:Control> <wsp:Policy> <throttle:MaximumCount>1</throttle:MaximumCount> <throttle:UnitTime>60000</throttle:UnitTime> </wsp:Policy> </throttle:Control> </wsp:Policy> </wsp:Policy> <wsp:Policy> <throttle:ID throttle:type="IP">other</throttle:ID> <wsp:Policy> <throttle:Control> <wsp:Policy> <throttle:MaximumCount>2</throttle:MaximumCount> <throttle:UnitTime>60000</throttle:UnitTime> </wsp:Policy> </throttle:Control> </wsp:Policy> </wsp:Policy> </throttle:MediatorThrottleAssertion></wsp:Policy>
API visibility and subscription
API visibility
Visibility settings prevent certain user roles from viewing and modifying APIs created by another user role.
- Public: The API is visible to all users (registered and anonymous), and can be advertised in multiple stores (central and non-WSO2 stores).
Restricted by Roles: The API is visible to it's tenant domain and only to the user roles that you specify.
Visible to my domain: The API is visible to all users who are registered to the API's tenant domain. This option is available only in a multi-tenanted environment. It's not applicable when there is only one active tenant in the system.
Given below is how visibility levels work for users in different roles:
- API
creatorandpublisherroles can see all APIs in their tenant store even if you restrict access to them. This is because those roles have permission to view and edit all APIs in the API Publisher, and therefore, does not have to be restricted in the Store. - Anonymous users can only see APIs that have visibility as
Public. - Registered users can see
- public APIs of all tenant domains
- all APIs in the registered user's tenant domain as long as the API is not restricted to a role that the user is assigned to
Subscription availability
The subscription availability option has three values as follows. You can set subscription availability to an API through the API Publisher's Manage tab.
- Available to current Tenant Only: only users in the current organization/tenant domain can subscribe to the API
- Available to All the Tenants: users of all organizations/tenant domains can subscribe to the API
- Available to Specific Tenants: users of the organizations/tenant domains that you specify as well as the current tenant domain can subscribe to the API
Subscription is available only to the current tenant in the following instances:
- When there is only one tenant in your system.
- Even if there are multiple tenants in your system, when you select Visible to my domain or Restricted by roles as the API's visibility in the previous step.
The diagram below depicts the relationship between the API's visibility and subscription availability:
API documentation visibility
By default, any document associated with an API has the same visibility level of the API. That is, if the API is public, its documentation is also visible to all users (registered and anonymous). To enable other visibility levels to the documentation, go to <AM_HOME>/repository/conf/api-manager.xml file, uncomment and set the following element to true:
| Code Block | ||
|---|---|---|
| ||
<APIPublisher>
....
<EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels>
</APIPublisher> |
Then, log in to the API Publisher, go to the Doc tab and click Add new Document to see a new drop-down list added to select visibility from:
You set visibility in the following ways:
- Same as API visibility: Visible to the same user roles who can see the API. For example, if the API's visibility is public, its documentation is visible to all users.
- Visible to my domain: Visible to all registered users in the API's tenant domain.
- Private: Visible only to the users who have permission to log in to the API Publisher Web interface and create and/or publish APIs to the API Store.
API resources
An API is made up of one or more resources, each of which handles a particular type of request. A resource has a set of methods that operate on it. The methods is analogous to a method or a function, and a resource is analogous to an object instance or a class in an object-oriented programming language. There are a few standard methods defined for a resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods.)
The diagram below shows a resource by the name CheckPhoneNumber added with four HTTP methods.
When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.
| URL Pattern | A URL pattern can be one of the following types:
The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:
url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching. Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of Also see http://tools.ietf.org/html/rfc6570 on URI templates. |
Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The default in-sequence, out-sequence and fault sequences are generated when the API is published.
HTTP methods
HTTP methods specify the desired action to be performed on an API's resource. You can select multiple methods from GET, POST, PUT, DELETE and OPTIONS. A method has attributes such as an OAuth scope, authentication type, response content type, parameters etc. as the diagram below shows:
The main attributes of a method are described below:
| OAuth scopes | You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. |
| Authentication type | The authentication type can be one of the following:
Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. (The above screenshot shows this). The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type. |
| Response content type | You can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be. |
| Parameters | Parameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway. |
Cross-origin resource sharing
Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g., fonts, JavaScript) of a Web page to be requested from another domain outside the domain from which the resource originated.
The Swagger API Console that is integrated in the API Manager runs as a JavaScript client in the API Store and makes calls from the Store to the API Gateway. Therefore, if you have the API Store and Gateway running on different ports, enable CORS between them.
The CORS configuration is in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample code.
| Code Block | ||
|---|---|---|
| ||
<CORSConfiguration>
<Enabled>true</Enabled>
<Access-Control-Allow-Origin>https://localhost:9443,http://localhost:9763</Access-Control-Allow-Origin>
<Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type</Access-Control-Allow-Headers>
</CORSConfiguration> |
The elements are described below:
| XML Elements | Values | Description |
|---|---|---|
| <Enabled> | True/False | Used to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly. |
| <Access-Control-Allow-Origin> | HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 | The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly. |
| <Access-Control-Allow-Headers> | Header values you need to pass when invoking the API. For example, | Default values are sufficient for Swagger to function. |
Change your code according to the sample given here.
If you try to invoke an API with inline endpoints, you add the CORS Handler in the <handlers> section of the API's configuration as follows. Find the API's configuration in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api folder.
| Code Block | ||
|---|---|---|
| ||
<handlers>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler"/>
</handlers> |
OAuth scopes
Scopes enable fine-grained access control to API resources based on user roles. You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.
You can apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button. A screen such as the following appears:
| Scope Key | A unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly. |
| Scope Name | A human-readable name for the scope. It typically says what the scope does. |
| Roles | The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee. |
To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API:
Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.
Tom requests a token through the Token API as grant_type=password&username=nuwan&password=xxxx&scope=news_read news_write. However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API will be similar to the following:
| Code Block |
|---|
"scope":"news_read","token_type":"bearer","expires_in":3299,
"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8" |
Next, John requests a token as grant_type=password&username=john&password=john123&scope=news_read news_write. As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:
| Code Block |
|---|
"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"4ca244fb321bd555bd3d555df39315",
"access_token":"42a377a0101877d1d9e29c5f30857e" |
This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:
| Code Block |
|---|
<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
<ams:code>900910</ams:code>
<ams:message>The access token does not allow you to access the requested resource</ams:message>
<ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8
</ams:description>
</ams:fault> |
...
Tip If you need to add a list of IPs / subnets for throttling you can derive the IP range from CIDR (Classless Inter-Domain Routing) notation and add it to the throttling policy configuration as follows.
Example :
If IP / subnet is "10.1.1.1/27" in CIDR notation, the IP address range is between "10.1.1.1 - 10.1.1.30" (if we keep 31 for broadcast). Therefore you can add throttling for the IP range as follows.
Code Block <throttle:ID throttle:type="IP">10.1.1.1 - 10.1.1.30</throttle:ID>
...
API visibility and subscription
API visibility
Visibility settings prevent certain user roles from viewing and modifying APIs created by another user role.
- Public: The API is visible to all users (registered and anonymous), and can be advertised in multiple stores (central and non-WSO2 stores).
Restricted by Roles: The API is visible to it's tenant domain and only to the user roles that you specify.
Visible to my domain: The API is visible to all users who are registered to the API's tenant domain. This option is available only in a multi-tenanted environment. It's not applicable when there is only one active tenant in the system.
Given below is how visibility levels work for users in different roles:
- API
creatorandpublisherroles can see all APIs in their tenant store even if you restrict access to them. This is because those roles have permission to view and edit all APIs in the API Publisher, and therefore, does not have to be restricted in the Store. - Anonymous users can only see APIs that have visibility as
Public. - Registered users can see
- public APIs of all tenant domains
- all APIs in the registered user's tenant domain as long as the API is not restricted to a role that the user is assigned to
Subscription availability
The subscription availability option has three values as follows. You can set subscription availability to an API through the API Publisher's Manage tab.
- Available to current Tenant Only: only users in the current organization/tenant domain can subscribe to the API
- Available to All the Tenants: users of all organizations/tenant domains can subscribe to the API
- Available to Specific Tenants: users of the organizations/tenant domains that you specify as well as the current tenant domain can subscribe to the API
Subscription is available only to the current tenant in the following instances:
- When there is only one tenant in your system.
- Even if there are multiple tenants in your system, when you select Visible to my domain or Restricted by roles as the API's visibility in the previous step.
The diagram below depicts the relationship between the API's visibility and subscription availability:
...
API documentation visibility
By default, any document associated with an API has the same visibility level of the API. That is, if the API is public, its documentation is also visible to all users (registered and anonymous). To enable other visibility levels to the documentation, go to <AM_HOME>/repository/conf/api-manager.xml file, uncomment and set the following element to true:
| Code Block | ||
|---|---|---|
| ||
<APIPublisher>
....
<EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels>
</APIPublisher> |
Then, log in to the API Publisher, go to the Doc tab and click Add new Document to see a new drop-down list added to select visibility from:
You set visibility in the following ways:
- Same as API visibility: Visible to the same user roles who can see the API. For example, if the API's visibility is public, its documentation is visible to all users.
- Visible to my domain: Visible to all registered users in the API's tenant domain.
- Private: Visible only to the users who have permission to log in to the API Publisher Web interface and create and/or publish APIs to the API Store.
...
API resources
An API is made up of one or more resources, each of which handles a particular type of request. A resource has a set of methods that operate on it. The methods is analogous to a method or a function, and a resource is analogous to an object instance or a class in an object-oriented programming language. There are a few standard methods defined for a resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods.)
The diagram below shows a resource by the name CheckPhoneNumber added with four HTTP methods.
When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.
| URL Pattern | A URL pattern can be one of the following types:
The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:
url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching. Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of Also see http://tools.ietf.org/html/rfc6570 on URI templates. |
Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The default in-sequence, out-sequence and fault sequences are generated when the API is published.
...
HTTP methods
HTTP methods specify the desired action to be performed on an API's resource. You can select multiple methods from GET, POST, PUT, DELETE and OPTIONS. A method has attributes such as an OAuth scope, authentication type, response content type, parameters etc. as the diagram below shows:
The main attributes of a method are described below:
| OAuth scopes | You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. |
| Authentication type | The authentication type can be one of the following:
Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. (The above screenshot shows this). The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type. |
| Response content type | You can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be. |
| Parameters | Parameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway. |
...
Cross-origin resource sharing
Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g., fonts, JavaScript) of a Web page to be requested from another domain outside the domain from which the resource originated.
The Swagger API Console that is integrated in the API Manager runs as a JavaScript client in the API Store and makes calls from the Store to the API Gateway. Therefore, if you have the API Store and Gateway running on different ports, enable CORS between them.
The CORS configuration is in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample code.
| Code Block | ||
|---|---|---|
| ||
<CORSConfiguration>
<Enabled>true</Enabled>
<Access-Control-Allow-Origin>https://localhost:9443,http://localhost:9763</Access-Control-Allow-Origin>
<Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type</Access-Control-Allow-Headers>
</CORSConfiguration> |
The elements are described below:
| XML Elements | Values | Description |
|---|---|---|
| <Enabled> | True/False | Used to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly. |
| <Access-Control-Allow-Origin> | HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 | The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly. |
| <Access-Control-Allow-Headers> | Header values you need to pass when invoking the API. For example, | Default values are sufficient for Swagger to function. |
Change your code according to the sample given here.
If you try to invoke an API with inline endpoints, you add the CORS Handler in the <handlers> section of the API's configuration as follows. Find the API's configuration in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api folder.
| Code Block | ||
|---|---|---|
| ||
<handlers>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler"/>
</handlers> |
...
OAuth scopes
Scopes enable fine-grained access control to API resources based on user roles. You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.
How scopes work
To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API:
Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.
Tom requests a token through the Token API as grant_type=password&username=tom&password=xxxx&scope=news_read news_write. However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API will be similar to the following:
| Code Block |
|---|
"scope":"news_read","token_type":"bearer","expires_in":3299,
"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8" |
Next, John requests a token as grant_type=password&username=john&password=john123&scope=news_read news_write. As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:
| Code Block |
|---|
"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"4ca244fb321bd555bd3d555df39315",
"access_token":"42a377a0101877d1d9e29c5f30857e" |
This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:
| Code Block |
|---|
<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
<ams:code>900910</ams:code>
<ams:message>The access token does not allow you to access the requested resource</ams:message>
<ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8
</ams:description>
</ams:fault> |
Applying a scope
You apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button under Resources. A screen such as the following appears:
| Scope Key | A unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly. |
| Scope Name | A human-readable name for the scope. It typically says what the scope does. |
| Roles | The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee. |
| Tip |
|---|
Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.
|
Scope whitelisting
A scope is not always used for controlling access to a resource. You can also use it to simply mark an access token. There are scopes that cannot be associated to roles (e.g., openid, device_). Such scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.
If you do not want a role validation for a scope in an API's request, add the scope under the APIKeyValidation element in the <APIM_HOME>/repository/conf/api-manager.xml file and restart the server. It will be whitelisted. For example,
| Code Block |
|---|
^device_.*
some_random_scope |
Next, invoke the Token API to get a token for the scope that you just whitelisted. For example,
| Code Block |
|---|
curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh" -H "Content-Type: application/x-www-form-urlencoded" https://10.100.0.3:8243/token |
Note that the issued token has the scope you requested. You get the token without any role validation as the scope is whitelisted.
| Code Block |
|---|
{"scope":"some_random_scope","token_type":"bearer","expires_in":3600,"refresh_token":"59e6676db0addca46e68991e44f2b8b8","access_token":"48855d444db883171c347fa21ba77e8"} |
...
API templates
An API template is its XML representation, which is saved in <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. This file comes with the API Manager by default. You can edit this default template to change the synapse configuration of all APIs that are created.
...
Overview
Content Tools
Activity