Handboek Annuleren

Authentication types

  1. ColdFusion User Guide
  2. Introduction to ColdFusion
    1. About Adobe ColdFusion
    2. Download Adobe ColdFusion
    3. What's new in ColdFusion (2021 release)
    4. ColdFusion (2021 release) Release Notes
    5. Deprecated Features
    6. REST enhancements in ColdFusion (2018 release)
    7. Server Auto-Lockdown
    8. Asynchronous programming
    9. Docker images for ColdFusion
  3. Adobe ColdFusion (2021 release)
    1. Install ColdFusion- Zip Installer
    2. Install ColdFusion- GUI Installer
    3. ColdFusion Licensing and Activation
    4. ColdFusion Package Manager
    5. CFSetup configuration tool
    6. SAML in ColdFusion
    7. ColdFusion and Amazon S3
    8. ColdFusion and DynamoDB
    9. ColdFusion and Amazon SQS
    10. ColdFusion and Amazon SNS
    11. ColdFusion and MongoDB
    12. ColdFusion and Azure Blob
    13. ColdFusion and Azure Service Bus
    14. New and updated language enancements
    15. Multi-cloud storage services
    16. Multi-cloud RDS databases
    17. ColdFusion and Azure Cosmos DB
  4. Install ColdFusion
    1. ColdFusion server profiles
    2. Prepare to install ColdFusion
    3. Install the server configuration
    4. Install the JEE configuration
    5. Install ColdFusion Express
    6. Install integrated technologies
    7. Configure your system
    8. Troubleshoot installation issues
    9. Install ColdFusion silently
    10. Install Adobe ColdFusion (2016 release) hotfix
    11. ColdFusion (2018 release) - Install JEE configuration
  5. Use ColdFusion
    1. Command Line Interface (CLI)
    2. External session storage
    3. Generate Swagger documents
    4. Language enhancements
    5. NTLM support
    6. New and changed functions/tags in Adobe ColdFusion (2016 release)
    7. PDF enhancements
    8. Security enhancements in ColdFusion (2016 release)
  6. Performance Monitoring Toolset
    1. Auto-discovery of ColdFusion nodes and clusters
    2. Code profiler in ColdFusion Performance Monitoring Toolset
    3. Configure ColdFusion Performance Monitoring Toolset settings
    4. Install ColdFusion Performance Monitoring Toolset
    5. Overview of ColdFusion Performance Monitoring Toolset
    6. View cluster and node metrics
    7. View data source metrics
    8. View external services
    9. View incoming services
    10. View list of sites and busy connections
    11. View topology of sites
    12. Datastore Health Monitoring
    13. Performance Monitoring Toolset Update 1
    14. Secure Performance Monitoring Toolset with HTTPS/SSL
    15. Performance Monitoring Toolset deployment guide
  7. Use ColdFusion Builder
    1. About ColdFusion Builder
    2. System requirements | ColdFusion Builder
    3. Install ColdFusion Builder
    4. Edit code in ColdFusion Builder
    5. Manage servers in ColdFusion Builder
    6. Manage projects in ColdFusion Builder
    7. What’s new in Adobe ColdFusion Builder (2018 release)
    8. Frequently Asked Questions (FAQ) | Adobe ColdFusion Builder (2018 release)
    9. Debug applications in ColdFusion Builder
    10. ColdFusion Builder workbench
    11. ColdFusion Builder extensions
    12. Debugging Perspective in ColdFusion Builder
    13. Build mobile applications using ColdFusion Builder
    14. Bundled ColdFusion Server
    15. Debug mobile applications in ColdFusion Builder
    16. Use extensions in ColdFusion Builder
  8. Coldfusion API Manager
    1. Overview of Adobe ColdFusion API Manager
    2. Features in ColdFusion API Manager
    3. Get started with ColdFusion API Manager
    4. Install ColdFusion API Manager
    5. Authentication types
    6. Create and publish APIs
    7. Administrator
    8. Subscriber
    9. Throttling and rate limiting
    10. Notifications
    11. Connectors
    12. Set up cluster support
    13. Integrate ColdFusion and API Manager
    14. Metrics and Logging in API Manager
    15. Generate Swagger documents
    16. Configure SSL
    17. Known issues in this release
    18. Policies in ColdFusion API Manager
    19. Create a Redis cluster
    20. Multitenancy in API Manager
    21. Docker images for ColdFusion API Manager
  9. Configure and administer ColdFusion
    1. Administer ColdFusion
    2. Use the ColdFusion administrator
    3. Data Source Management for ColdFusion
    4. Connect to web servers
    5. Deploy ColdFusion applications
    6. Administer ColdFusion security
    7. Basic Troubleshooting and FAQs
    8. Work with Server Manager
    9. Use multiple server instances
    10. WebSocket Enhancements (ColdFusion 11)
    11. Security Enhancements (ColdFusion 11)
    12. Work with Server Monitor
    13. ColdFusion Administrator API Reference
  10. CFML Reference
    1. Introduction to CFML Reference
      1. New functions in ColdFusion (2018 release)
      2. New and changed functions/tags in Adobe ColdFusion (2016 release)
      3. Script supported tags and functions
      4. New and changed tags/functions in ColdFusion 11
    2. Reserved words and variables
      1. Reserved words and variables
      2. Reserved words
      3. Scope-specific built-in variables
      4. Custom tag variables
      5. ColdFusion tag-specific variables
      6. CGI environment (CGI Scope) variables
    3. ColdFusion tags
      1. ColdFusion tags
      2. Tags in ColdFusion 10
      3. Tag summary
      4. Tags by function
      5. Tag changes since ColdFusion 5
      6. Tags a-b
      7. Tags c
      8. Tags d-e
      9. Tags f
      10. Tags g-h
      11. Tags i
      12. Tags j-l
      13. Tags m-o
      14. Tags p-q
      15. Tags r-s
      16. Tags t
      17. Tags u-z
    4. ColdFusion functions
      1. ColdFusion functions
      2. New functions in ColdFusion 10
      3. ColdFusion functions by category
      4. Function changes since ColdFusion 5
      5. Functions a-b
      6. Functions c-d
      7. Functions e-g
      8. Functions h-im
      9. Functions in-k
      10. Functions l
      11. Functions m-r
      12. Functions s
      13. Functions t-z
      14. BooleanFormat
    5. Ajax JavaScript functions
      1. Ajax JavaScript functions
      2. Function summary Ajax
      3. ColdFusion.Ajax.submitForm
      4. ColdFusion.Autosuggest.getAutosuggestObject
      5. ColdFusion.Layout.enableSourceBind
      6. ColdFusion.MessageBox.getMessageBoxObject
      7. ColdFusion.ProgressBar.getProgressBarObject
      8. ColdFusion.MessageBox.isMessageBoxDefined
      9. JavaScriptFunctionsinColdFusion9Update1
    6. ColdFusion ActionScript functions
      1. ColdFusion ActionScript functions
      2. CF.http
      3. CF.query
    7. ColdFusion mobile functions
      1. ColdFusion Mobile Functions
      2. Accelerometer Functions
      3. Camera Functions
      4. Connection Functions
      5. Contact Functions
      6. Event Functions
      7. File System Functions
      8. Geolocation Functions
      9. Media and Capture Functions
      10. Notification Functions
      11. Splash Screen Functions
      12. Storage Functions
    8. Application.cfc reference
      1. Application.CFC reference
      2. Application variables
      3. Method summary
      4. onAbort
      5. onApplicationEnd
      6. onApplicationStart
      7. onMissingTemplate
      8. onCFCRequest
      9. onError
      10. onRequestEnd
      11. onRequest
      12. onRequestStart
      13. onServerStart
      14. onSessionEnd
      15. onSessionStart
    9. Script functions implemented as CFCs
      1. Script Functions Implemented as CFCs
      2. Accessing the functions
      3. Function summary
      4. ftp
      5. http
      6. mail
      7. pdf
      8. query
      9. Script functions implemented as CFCs in ColdFusion 9 Update 1
      10. storedproc
    10. ColdFusion Flash Form style reference
      1. Styles valid for all controls
      2. Styles for cfform
      3. Styles for cfformgroup with horizontal or vertical type attributes
      4. Styles for box-style cfformgroup elements
      5. Styles for cfformgroup with accordion type attribute
      6. Styles for cfformgroup with tabnavigator type attribute
      7. Styles for cfformitem with hrule or vrule type attributes
      8. Styles for cfinput with radio, checkbox, button, image, or submit type attributes
      9. Styles for cftextarea tag and cfinput with text, password, or hidden type attributes
      10. Styles for cfselect with size attribute value of 1
      11. Styles for cfselect with size attribute value greater than 1
      12. Styles for cfcalendar tag and cfinput with dateField type attribute
      13. Styles for the cfgrid tag
      14. Styles for the cftree tag
      15. ColdFusion Flash Form Style Reference
    11. ColdFusion event gateway reference
      1. ColdFusion Event Gateway reference
      2. addEvent
      3. CFEvent
      4. CFEventclass
      5. Constructor
      6. Gateway development interfaces and classes
      7. getStatus
      8. setCFCPath
      9. setCFCMethod
      10. getOriginatorID
      11. getLogger
      12. getBuddyList
      13. getBuddyInfo
      14. IM gateway message sending commands
      15. IM Gateway GatewayHelper class methods
      16. onIncomingMessage
      17. onIMServerMessage
      18. onBuddyStatus
      19. onAddBuddyResponse
      20. onAddBuddyRequest
      21. IM Gateway CFC incoming message methods
      22. IM gateway methods and commands
      23. CFML CFEvent structure
      24. warn
      25. info
      26. setOriginatorID
      27. data command
      28. submit Multi command
      29. submit command
      30. setGatewayType
      31. setGatewayID
      32. setData
      33. setCFCListeners
      34. outgoingMessage
      35. getStatusTimeStamp
      36. numberOfMessagesReceived
      37. numberOfMessagesSent
      38. removeBuddy
      39. removeDeny
      40. removePermit
      41. setNickName
      42. setPermitMode
      43. setStatus
      44. SMS Gateway CFEvent structure and commands
      45. SMS Gateway incoming message CFEvent structure
      46. getStatusAsString
      47. getProtocolName
      48. getPermitMode
      49. getPermitList
      50. getNickName
      51. getName
      52. getDenyList
      53. getCustomAwayMessage
      54. getQueueSize
      55. getMaxQueueSize
      56. getHelper
      57. getGatewayType
      58. getGatewayServices
      59. getGatewayID_1
      60. getGatewayID
      61. getData
      62. getCFCTimeout
      63. setCFCTimeout
      64. getCFCPath
      65. getCFCMethod
      66. GatewayServices class
      67. Gateway interface
      68. GatewayHelper interface
      69. addPermit
      70. addDeny
      71. addBuddy
      72. error
      73. debug
      74. Logger class
      75. stop
      76. start
      77. CFML event gateway SendGatewayMessage data parameter
      78. restart
      79. fatal
      80. SMS gateway message sending commands
    12. ColdFusion C++ CFX Reference
      1. C++ class overview
      2. Deprecated class methods
      3. CCFXException class
      4. CCFXQuery class
      5. CCFXRequest class
      6. CCFXStringSet class
      7. ColdFusion C++ CFX Reference
    13. ColdFusion Java CFX reference
      1. ColdFusion Java CFX reference
      2. Class libraries overview
      3. Custom tag interface
      4. Query interface
      5. Request interface
      6. Response interface
      7. Debugging classes reference
    14. WDDX JavaScript Objects
      1. WDDX JavaScript objects
      2. JavaScript object overview
      3. WddxRecordset object
      4. WddxSerializer object
  11. Develop ColdFusion applications
    1. Introducing ColdFusion
      1. Introducing ColdFusion
      2. About ColdFusion
      3. About Internet applications and web application servers
      4. About JEE and the ColdFusion architecture
    2. Changes in ColdFusion
      1. Changes in ColdFusion
      2. Replacement of JRun with Tomcat
      3. Security enhancements
      4. ColdFusion WebSocket
      5. Enhanced Java integration
      6. ColdFusion ORM search for indexing and search
      7. Solr enhancements
      8. Scheduler enhancements
      9. Integration with Microsoft Exchange Server 2010
      10. RESTful Web Services in ColdFusion
      11. Lazy loading across client and server in ColdFusion
      12. Web service enhancements
      13. Displaying geolocation
      14. Client-side charting
      15. Caching enhancements
      16. Server update using ColdFusion Administrator
      17. Secure Profile for ColdFusion Administrator
    3. Introduction to application development
      1. Introduction to application development using ColdFusion
      2. Using the Developing ColdFusion Applications guide
      3. About Adobe ColdFusion documentation for Developers
    4. The CFML programming language
      1. The CFML programming language
      2. Elements of CFML
      3. ColdFusion variables
      4. Expressions and number signs
      5. Arrays and structures
      6. Extend ColdFusion pages with CFML scripting
      7. Regular expressions in functions
      8. ColdFusion language enhancements
      9. Built-in functions as first class citizen
      10. Data types- Developing guide
    5. Building blocks of ColdFusion applications
      1. Building blocks of ColdFusion applications
      2. Create ColdFusion elements
      3. Write and call user-defined functions
      4. Build and use ColdFusion Components
      5. Create and use custom CFML tags
      6. Build custom CFXAPI tags
      7. Use the member functions
      8. Object Oriented Programming in ColdFusion
    6. Develop CFML applications
      1. Develop CFML applications
      2. Design and optimize a ColdFusion application
      3. Handle errors
      4. Use persistent data and locking
      5. Use ColdFusion threads
      6. Secure applications
      7. Client-side CFML (for mobile development)
      8. Use the ColdFusion debugger
      9. Debugging and Troubleshooting Applications
      10. Develop globalized applications
      11. REST enhancements in ColdFusion
      12. Authentication through OAuth
      13. Social enhancements
    7. Develop mobile applications
      1. Mobile application development
      2. Build mobile applications
      3. Debug mobile applications
      4. Inspect mobile applications
      5. Package mobile applications
      6. Troubleshoot mobile applications
      7. Device detection
      8. Client-side CFML
      9. Mobile Templates
      10. Code samples to build a mobile application
    8. Access and use data
      1. Access and use data
      2. Introduction to Databases and SQL
      3. Access and retrieve data
      4. Update database
      5. Use Query of Queries
      6. Manage LDAP directories
      7. Solr search support
    9. ColdFusion ORM
      1. ColdFusion ORM
      2. Introducing ColdFusion ORM
      3. ORM architecture
      4. Configure ORM
      5. Define ORM mapping
      6. Work with objects
      7. ORM session management
      8. Transaction and concurrency
      9. Use HQL queries
      10. Autogenerate database schema
      11. Support for multiple data sources for ORM
      12. ColdFusion ORM search
    10. ColdFusion and HTML5
      1. ColdFusion and HTML 5
      2. Use ColdFusion Web Sockets
      3. Media Player enhancements
      4. Client-side charting
      5. Display geolocation data
    11. Flex and AIR integration in ColdFusion
      1. Flex and AIR integration in ColdFusion
      2. Use the Flash Remoting Service
      3. Use Flash Remoting Update
      4. Offline AIR application support
      5. Proxy ActionScript classes for ColdFusion services
      6. Use LiveCycle Data Services ES assembler
      7. Use server-side ActionScript
    12. Request and present information
      1. Request and present information
      2. Retrieve and format data
      3. Build dynamic forms with cfform tags
      4. Validate data
      5. Create forms in Flash
      6. Create skinnable XML forms
      7. Use Ajax data and development features
      8. Use Ajax User Interface components and features
    13. Office file interoperability
      1. Office file interoperability
      2. Using cfdocument
      3. Using cfpresentation
      4. Using cfspreadsheet
      5. Supported Office conversion formats
      6. SharePoint integration
    14. ColdFusion portlets
      1. ColdFusion portlets
      2. Run a ColdFusion portlet on a JBoss portal server
      3. Run a ColdFusion portlet on a WebSphere portal server
      4. Common methods used in portlet.cfc
      5. ColdFusion portlet components
      6. Support for JSR-286
    15. Work with documents, charts, and reports
      1. Work with documents, charts, and reports
      2. Manipulate PDF forms in ColdFusion
      3. Assemble PDF documents
      4. Create and manipulate ColdFusion images
      5. Create charts and graphs
      6. Create reports and documents for printing
      7. Create reports with Report Builder
      8. Create slide presentations
    16. Use web elements and external objects
      1. Use web elements and external objects
      2. Use XML and WDDX
      3. Use web services
      4. Use ColdFusion web services
      5. Integrate JEE and Java elements in CFML applications
      6. Use Microsoft .NET assemblies
      7. Integrate COM and CORBA objects in CFML applications
    17. Use external resources
      1. Send and receive e-mail
      2. Interact with Microsoft Exchange servers
      3. Interact with remote servers
      4. Manage files on the server
      5. Use event gateways
      6. Create custom event gateways
      7. Use the ColdFusion extensions for Eclipse
      8. Use the data services messaging event gateway
      9. Use the data management event gateway
      10. Use the FMS event gateway
      11. Use the instant messaging event gateways
      12. Use the SMS event gateway

 

Overview

In the API Manager, you can use API keys to authenticate your APIs and applications. The API Manager generates the API keys and enable you to add API key-based authentication to your APIs.

Validation using API keys is a type of security you can enforce while creating an API. Applications use the API key and the API Manager checks to see if the API key is in an approved state for a resource.

The API Manager uses three API authentication types:

  1. apiKey
  2. basicAuth
  3. OAuth2

OAuth2

In any traditional client-server application when the client requests for a protected resource or web page, the server authenticates the client. The client passes the credentials to the server and the authentication happens. Based on the authentication result, the client gets access to the protected resource. This approach works fine in a controlled environment where an organization/entity manages both the client and server applications.

Today’s organizations adopt an open and collaborative platform architecture in which the data is shared through an API mechanism. The API mechanism allows any developer (internal or customers) to quickly interact with the service without the intervention of the service owner. This framework enables users to build mashups, mobile and desktop client applications, and other third-party services.

The services often require access to sensitive data of an API which in turn requires authentication or access control. One common method of authentication is the user name and password authentication. However, providing password to a third-party application has many disadvantages. Entering a password in a third-party application requires a user’s trust. Also, from a usability perspective, it is not possible to revoke an application until the password has changed. In the same way, the application fails to work reliably if the password has changed.

OAuth2 combats the risks mentioned above, that are associated with the password anti-pattern. OAuth2 is a standard for delegating authorization to an application on behalf of the user without providing the password. Instead of the user password, an application receives an access token with limited lifetime access. Depending on the type of application, obtaining an access token varies. These access tokens are called grant types. To know more about OAuth 2.0, refer to IETF OAuth 2.0 specification.

OAuth2: Terms and actors

Resource owner

An entity capable of granting access to a protected API. A resource owner can be an end user.  The resource owner delegates authorization to the third-party client or application. Through this delegation, the application can access the API on behalf of resource owner.

Resource Server

The server hosting the APIs. The resource server accepts and responds to protected API requests using access tokens. The API Manager acts as resource server that validates access tokens and performs access-control on a protected API.

Client

An application that makes protected resource requests on behalf of the resource owner and the owner’s authorization.  The term "client" does not imply to any particular implementation characteristics (for example, if the application executes on a server, a desktop, or other devices). The API Manager application is an OAuth2 client.

Authorization Server

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. The API Manager acts as an authorization server as well.

Access Token

Access tokens are credentials to access protected APIs.  An access token is a string representing an authorization issued to the client.  The string is opaque to the client.  Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server. The API Manager currently supports Bearer Access tokens which are opaque tokens.

Refresh Token

Refresh tokens are credentials used to obtain access tokens. The authorization server issues the refresh tokens to the client. The client obtains refresh tokens when the current token becomes invalid or expires.

Authorization Code

An opaque code obtained through authorization code grant flow can be redeemed to get a limited life time access token and a refresh token. Once code is redeemed, it is no longer valid and cannot be used to get access tokens.

Scope

A scope is a permission associated with a protected resource. If the publisher protects any resource using OAuth2, specifying a scope along with it requires the access token to have this scope associated with it.

Client ID

Every application with OAuth2 authorization has a unique identifier.

Client Secret

The Client Secret gets the access token in Client credentials flow and authorization code flow.

The API Manager provides complete OAuth2 support including authentication provider, role-based authorization framework for scopes, and login web pages along with token management component. The API Manager acts as authorization server and resource server. The authentication provider supports integration with LDAP, database, and federated authentication using SAML. 

OAuth2 endpoints

The API Manager OAuth2 provider provides the following endpoints which are used to obtain and manage access tokens:

Authorization Endpoint

http(s)://servername:serverport/oauth2/auth: The endpoint where the end user logs in and provides the consent to provision the authorization grant to the application.

Token Endpoint

http(s)://servername:serverport/oauth2/token: The endpoint that the client uses to obtain an access token by presenting its authorization grant or refresh token.

Redirect Endpoint

After the user interacts with the authorization endpoint, a user is redirected back to the application. The redirect (or callback) URL is specified in the application created in the API Manager. Currently, the API Manager does not support multiple redirect URL’s registration in the application.

Token Info Endpoint

http(s)://servername:serverport/oauth2/tokeninfo: The tokeninfo endpoint provides information about the access token. The response of the endpoint includes information like create time, expiry, Application Id (client_id) of the logged in user, and scopes.

The token info endpoint receives the access token in two ways:

1.       Using query parameter access_token

2.       Using the authorization header

Example of a simple HTTP GET request with query parameter access _token:

http(s)://example.com/oauth2/tokeninfo?access_token=3ffb313f16856a4d6b1feecd2e50b950

(or) using the authorization header:

GET example.com/oauth2/token HTTP/1.1

Host: example.com

Authorization: Bearer 3ffb313f16856a4d6b1feecd2e50b950

Token Revocation Endpoint

http(s)://servername:serverport/oauth2/revoke: The endpoint that can be used to revoke any access token or refresh token. Once revoked, the access token or refresh token becomes invalid.

OAuth2 Self Service

http(s)://servername:serverport/oauth2/self/<Logon Identifier>: If the OAuth2 server authentication provider is a user store (LDAP or database), an end user can view the list of approved applications along with the approved scopes. The end user can also revoke any application access. Configure the login identifier in the user store to set up this portal.

Application Registration

To obtain access tokens or authorization codes, register the application with the API Manager. The API Manager authorization server identifies the application. Registering an application with the API manager provides the following pair of keys:

  • client Id: Client Id is a public identifier
  • client secret: Client secret is a secret identifier

Register the callback URL (or redirect URL) of the application with the API Manager so that the deployed application can access the token. To use any of OAuth2 grant types, the API Manager subscribes to at least one API that is protected using OAuth2.

Grant types

A grant is a method of acquiring an access token that accesses an OAuth2- protected API. OAuth2 provides different grant types for different scenarios based on the type of application (server, browser, or mobile).

Client credentials grant type

Among the four grant types of OAuth 2.0, client credentials is the simplest grant type. This grant type can be used in cases where an application that is confidential (means ability to store client credentials safely) consumes the API.

Prerequisites

Register an application with the API Manager. The application subscribes to at least one API that is protected using OAuth2.

Access Token Request

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs request is made using HTTP POST with the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

Request Parameter

Description of the parameter

grant_type

Specifies the requested grant type. To use this flow, the value is client_credentials.

client_id

The Id that uniquely identifies the application. The client id can be found in the API Manager application.

client_secret

Specifies the client credential registered with the application in API Manager.

scope (optional)

Specifies the list of scopes required for the access token. If multiple scopes are required, specify the scopes as a space-delimited string.

The sample below is an HTTP request to request an access token with scopes:

POST example.com/oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de&scope=sample_read%20sample_write

Both client Id and client secret can also be sent using the authorization header. The sample HTTP request requests an access token by passing the client credentials in authorization header along with scopes.

Authorization: Basic Base64 (clientId:clientSecret)

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sample_read%20sample_write

Access Token Response

If the request for the access token is successful, the response is sent in JSON Format. The JSON includes the following keys.

Response Parameter

Description of the Response Parameter

access_token

The access token that can be used to call the protected API.

token_type

Specifies the type of the requested access token. Currently the API Manager supports only bearer tokens.

expires_in

The lifetime in seconds of the access token. The access token lifetime can be configured by changing the access token lifetime in API Manager application.

scope (optional)

The Granted/Approved scopes associated with the requested access token.

 

The following example shows a JSON response:

{

  "access_token": "7ee85874dde4c7235b6c3afc82e3fb",

  "token_type": "bearer",

  "expires_in": 1200,

  "scope": " sample_read sample_write"

}

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. As this flow involves direct client authentication, the endpoint response does not include any user info.

Access Token Revocation

Every access token has an expiry time. The access token becomes invalid and revoked automatically when the token reaches its expiry time. When the token expires, applications request for a new token and is granted one. Client credentials flow/grant type does not grant any refresh token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint. When revoking the access token using client credentials, the flow requires passing the client credentials in the token revocation request for a second time.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the Access token issued using client credentials flow.

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de

Client Secret Regeneration

You can generate the Client Secret by logging into the portal to prevent any unauthorized access to the Client Secret.

Once the Client Secret is regenerated, the older Client Secret becomes invalid. Use the new Client Secret to request for new access tokens.

Security Considerations

The security of OAuth2 depends on the secure transmission of OAuth2 access tokens and client credentials. Therefore, access all the OAuth2 endpoints on HTTPS (SSL/TLS) transport for production environments.

You can choose Mandate HTTPS in the Security Configuration page in the API Manager administrator to prevent all OAuth2 endpoints from accepting any request over HTTP.  Keep the client secret confidential and store it in a secure database.

Keep the application private, otherwise the credentials can be captured by decompiling/analyzing the source code of the application. Use this flow on server-side application where secure storage can be guaranteed.

How is Client Credential grant different from API Keys security?

In case of client credentials, you use the access token is used to call the API. On the other hand, in API Key security, you can use the API key to validate the API. You get an extra layer of security control where you can revoke the access token easily without modifying the client application. 

Implicit/token grant type (two-legged OAuth2)

Implicit/token grant is one of the browser-based redirection flows that is suitable for pure JavaScript (client-side)-centric or mobile applications that cannot store user credentials and does not have any server side component.

A simple example is a pure JavaScript application made using Angular/Ember and calls the API directly from JavaScript via Ajax calls. This grant type/flow requires interaction with the end user.

Prerequisites

Register an application with the API Manager. The application subscribes to at least one API that is protected using OAuth2. Specify the callback URL (or redirection URL)  in the API Manager. After authorization request is completed, you are redirected to this registered URL. The registered application includes the client ID that is required for this flow/grant type.

Requesting an Access Token

The flow begins by the application by redirecting the user to API Manager OAuth2 server authorization endpoint (/oauth2/auth) when the application tries to access an OAuth2 protected API.  The URL for sending the authorization request is shown as below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=token&scope=<list of scopes delimited by string>&state=<random string>

For example,

 

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=token&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

 

Request Parameter

Description of the parameter

response_type

This parameter identifies this grant type flow. The value is token.

client_id

This parameter uniquely identifies the application. The client id can be found in the API Manager application.

state

This parameter is an opaque pseudo-random string value used by the client application to maintain state between the initial authorization request and callback. The parameter prevents cross-site request forgery. Store the scope locally when the flow starts after which can be used later for comparison.

Scope (optional)

Specifies the list of scopes required for the access token. If multiple scopes are required, specify the scopes as a space delimited string.

Once the API Manager OAuth2 server receives the request, it validates all the parameters. If valid, and the authentication method for application is user-store, you see a login page.  If the authentication method for the application is SAML SSO, you are redirected to the SAML Identity provider for authentication. After the authentication is successful, you are presented with another page where you can provide the authorization/consent.

Here, you can select the list of scopes that are permitted for the application, which in turn is provided to the access token.

Once it is redirected to the callback URL, the application has a script to extract the access token out of the URL fragment. The server does not receive the access token because the URL fragment is not sent over HTTP/S by browsers. The callback URL’s fragment contains the following parameters:

URL Fragment Parameter

Description of the parameter

access_token

The requested access token that can be used to call the protected API.

token_type

Specifies the type of the requested access token. Currently the API Manager supports bearer tokens only so the value is Bearer.

expires_in

The lifetime, in seconds, of the access token. The access token lifetime can be configured by changing the access token lifetime in API Manager application.

client_id

Client id of the application for which the access token is issued.

state

An opaque pseudo-random string value used by the client application to maintain state between the initial authorization request and callback. The parameter is used to prevent cross-site request forgery.

scope (optional)

The granted/approved scopes associated with the requested access token.

Once the access token is obtained from the grant type, it calls the protected API and gets the response from the API.

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. The API Manager OAuth2 authorization server does not issue any refresh tokens. Once the issued access token expires, the application goes through the OAuth2 two-legged process again.

The API Manager admin portal controls the timeout for the login credentials. If the authentication times out, provide valid credentials (user name and password) again to log in in case of user store authentication method. In case of SAML SSO IDP, authorization happens again. If the application is already approved, you are directly redirected to the callback URL with the fragment having the access token and other details.

Security Considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The API Manager administrator can mandate HTTPS transport only in the Security Configuration page. 

Also, register the HTTPs URL callback with the API Manager because the callback URL receives the access token. The application verifies the state parameter value received in the fragment with the value stored in the initial request. Also, verify that the client id from the URL fragment is same as the client id in the JavaScript application code.

Access Token Revocation

Every access token has an expiry time. Once it reaches the expiry time, the access token becomes invalid and is revoked automatically. Once the access token expires, the application makes a request for the access token again. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

Authorization code grant type (three-legged OAuth 2)

This grant type is suitable for server applications.  In this flow, the access token is hidden from the end user, and instead issues an authorization code.

Redeem the intermediary authorization code at the token endpoint with client credentials to receive access token and refresh token. This flow also requires application to have a server component where it redeems the authorization code for accessing the token and refreshing the token. Once the code is redeemed, it is no longer valid.

Prerequisites

Register an application with the API Manager and subscribe to at least one API that is protected using OAuth2. Also, specify a callback URL (or redirection URL) with the API Manager application so that after authorization request is completed user is redirected to this registered URL. The registered application includes Client ID and Client Secret, which are required for this flow/grant type.

Requesting an access token

The flow begins by the application server component redirecting the end user to API Manager OAuth2 server authorization endpoint (/oauth2/auth). The URL for sending the authorization request is shown below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=code&scope=<list of scopes delimited by string>&state=<random string>

An example URL is:

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=code&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

 

Request Parameter

Description of the parameter

response_type

The parameter identifies the flow of the grant type. The value is code.

client_id

The Client Id of the application which uniquely identifies the application. The client id can be found in the API Manager application.

state

An opaque pseudo- random string value used by the client application to maintain state between the initial authorization request and callback. The parameter is used to prevent cross-site request forgery. Store the state in a server-side session for comparing it later.

scope (optional)

Specifies the list of scopes required for the access token. If multiple scopes are required, specify the scopes as a space delimited string.

Once the API Manager OAuth2 server receives this request, it validates all the parameters. If the parameters are valid, the user sees a login page where the user is asked to provide the login credentials ( user name and password).  If the authentication method for the application is SAML SSO, the user is redirected to the SAML Identity provider for authentication.

After the authentication is successful, you are presented with another page where you can provide the authorization/consent. Here you can select the list of scopes that are permitted for the application, which in turn is provided to the access token. Once scopes are selected and approved, you are redirected (to the registered URL) back to the application. You attach a query parameter called code with its value along with the state parameter.

Now the application server component verifies the state parameter value received from the request with the value stored in the session. If state parameter is verified, then extract the code parameter value from the request and use client credentials to redeem this code for an access token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=9a42a56d5b5546079f2f82a62612dab9&

client_secret=7ee85874dde4c7235b6c3afc82e3fb

If the given client credentials & the authorization code are valid the response will contain an access token along with a refresh token. Refresh token is used to get a new access token when the current access token is expired/revoked. The JSON response includes the following keys.

A sample JSON response is shown below.

{

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 1200,

"scope": "foo_read",

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

 

JSON Key

Description of the Key

access_token

The requested access token which can be used to call the protected API.

token_type

Specifies the type of the requested access token. Currently API Manager supports bearer tokens only so the value is Bearer.

expires_in

The lifetime in seconds of the access token. The access token lifetime can be configured by changing the access token lifetime in API Manager application.

client_id

Client Id of the application for which the access token is issued.

State

An opaque pseudo- random string value used by the client application to maintain state between the initial authorization request and callback. The parameter is used to prevent cross-site request forgery.

scope

The Granted/Approved scopes associated with the requested access token.

refresh_token

Refresh token is a long-lived access token which is used to ask for a new access token.

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing access token

The example below shows how to refresh an access token using refresh token. Pass the client credentials along with the request, either through form parameters or using basic authentication.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&client_id=3ffb313f16856a4d6b1feecd2e50b950&scope=foo_read

If the refresh token is expired/revoked, the application starts the three-legged dance once again. In case of user store authentication, if the authentication times out, provide valid credentials ( user name and password) again to log in. In case of SAML SSO IDP, authorization happens again. If the application is already approved, you are redirected to the callback URL immediately with the intermediary authorization code and state.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes invalid & revoked automatically. Once the access token expires, the application gets a new access token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request revokes the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form- urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set token_type_hint parameter value as refresh_token.

Security considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 access tokens, and client credentials. Therefore, accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The API Manager administrator can mandate HTTPS transport only in the Security Configuration page.  Also, HTTPS URL callback is registered with the API Manager application because the callback URL receives the authorization code. The server application verifies the state parameter value received in the request with the value stored in the session. The server application securely stores the access tokens, refresh tokens, and client credentials in a secure database.

Resource owner/password grant type

This grant type allows the application to have their own login page. The password grant type is used in the cases where you have complete trust on the application. This grant type is suitable for a trusted mobile application or a desktop application. This grant type requires user interaction for requesting the access token.

Prerequisites

Register an application API Manager. It is mandatory that the application subscribes least one API that is protected using OAuth2. The registered application includes Client ID which is required for this flow/grant type. For this grant type to function, it is important that all subscribed APIs of type User store are configured with the same user store.

Requesting an Access Token

The user initiates the flow when accessing the installed application is presented with a login form provided by the application. User enters the login credentials (user name, password) then the application sends an authorization request to the API manager OAuth2 server.

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs request is made using HTTP POST having the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

Request Parameter

Description of the parameter

grant_type

Specifies the requested grant type. To use this flow, the value is password.

client_id

Client Id of the application which uniquely identifies the application. The client id can be found in the API Manager application.

user name

End user provided user name

password

End user provided password

scope (optional)

Specifies the list of scopes required for the access token. If multiple scopes are required, specify the scopes as a space delimited string.

POST /oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=password&username=maxwell&password=sdcoio2380&client_id= 95d9c3de53a9c48e629ecb6a288f6c&scope=foo_read%20foo_write

The API Manager Server validates the incoming request and checks whether the client id is valid and is allowed to use the password grant type.  Then it checks for the application authentication method is user store or not and authenticates the given user name and password against the user store. If the authentication is successful, the Oauth2 server validates the scopes requested.

If the requested scopes are not empty, each scope is looked at whether granting this scope requires any group/role membership. If user is part of the roles specified in the scope, that scope is approved. An access token with approved scopes along with a refresh token is returned as part of the response. The JSON response includes the following keys.

JSON Key

Description of the Key

access_token

The requested access token which can be used to call the protected API.

token_type

Specifies the type of the requested access token. Currently API Manager supports bearer tokens only so the value is Bearer.

expires_in

The lifetime of the access token in seconds. The access token lifetime can be configured by changing the access token lifetime in API Manager.

scope

The granted/approved scopes associated with the requested access token.

refresh_token

Refresh token is a long-lived access token which is used to ask for a new access token.

 

A sample JSON response is shown below:

{                                                             

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 2800,

"scope":"foo_read foo_write",                                                 

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing Access Token

The example below shows how to refresh an access token using refresh token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

If the refresh token is expired/revoked, the application asks you for the credentials. Restart the complete flow again.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes invalid and revoked automatically. Once access token expires, the application gets a new access token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the Access token

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set token_type_hint parameter value as refresh_token.

Security Considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The client application does not store user credentials anywhere and securely stores them. If it is a desktop application, use a secure database. If it is an Android mobile application, store the access tokens and refresh tokens using SharedPreferences API. If it is iOS, store the tokens in KeyChain.

Calling an OAuth2-protected API

Once an access token is obtained from any of the grant types, it can be used to call the OAuth2-protected API. The authorization header format is:

Authorization: Bearer <OAuth2 Access Token>

Pass the access token in the Authorization Header as shown below.

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Bearer 7ee85874dde4c7235b6c3afc82e3fb

Currently, the API Manager only issues bearer tokens. The API Manager validates the access token. If the token is valid, then the API Manager checks if the access token has the scope to call the protected API.

If both the conditions are true, then the API Manager calls the backend and gets the response and provides it to the client.

API Key authentication

An API Key is an opaque token, which is a simple form of authentication to consume an API.  To acquire an API Key, create an application as a subscriber.

Consuming an API protected using API Key

In a request, you can pass an API Key to the API Manager in a request in one of the following ways:

  • Header: The api_key header can be used to pass the API Key to the API runtime.
  • Query Parameter: The api_key query parameter can be used to pass the API Key.
  • Form Parameter: The api_key form parameter can be used to pass the API Key.

When consuming an API protected using API Key, API runtime checks for the API Key in the header. If the key is not found, then API runtime checks in the query parameters. If the key is not found, then the API runtime checks the form (or post) parameter.

If the extracted API Key is valid, the API Manager checks whether this API Key is approved or not. If the key is approved, the API manager gets the SLA plan for this subscription and then uses it for the rate limiting and throttling.

API Key regeneration

When an API Key is regenerated, the old Key of the application is no longer valid. The application starts using the new key to consume the API Key.

Basic authentication

Basic authentication is the simplest form of authenticating a user by passing the user name and password in the request when consuming an API. The API Manager allows protecting an API using the Basic authentication scheme.

A publisher can configure the user store to be used for the authentication. If the API resource is protected with a scope configured with roles, then the API Manager also authorizes the role. The authorization happens during the consumption of the API call.

Create an application in the API Manager and subscribe to an API protected using basic authentication.

With HTTP basic authentication, the user’s user name and password are concatenated, base64-encoded, and passed in the Authorization HTTP header as follows:

Authorization: BASIC Base64 (username:password)

example: Authorization: Basic dm9yZGVsOnZvcmRlbA==

But simply passing the user name or password does not identify the application consuming the API. Send the application unique identifier (client ID) along with the request.

An example of consuming an API protected using BASIC authentication is as follows:

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Basic dm9yZGVsOnZvcmRlbA==

clientid: 3ffb313f16856a4d6b1feecd2e50b950

Once the API Manager receives a request for an API that is protected using basic authentication, it looks for the application id. If the application id (client id) in the request is valid and approved, then the API Manager authenticates the credentials in the request.

If authentication is successful, then the API Manager checks if the current API requested is protected with appropriate scope and authorized role. If yes, the API Manager retrieves the user roles and checks if the current user has all the required roles to consume this API. Once role authorization is successful, the API Manager gets the SLA plan for this subscription for rate limiting and throttling. If rate limit is also allowed, the request is forwarded to get the response from the application.

Adobe-logo

Aanmelden bij je account