Configure OAuth for gadgets
The IBM Connections 4.5 release supports an OAuth 2.0 consumer proxy that allows the Homepage component to surface gadgets in an OpenSocial container that interacts with an OAuth 2.0 protected service. To enable, run the following new administration commands exposed in the News service (newsAdmin.py) to define OAuth 2.0 providers, clients, and associated gadgets that will interact with the protected service.
Count providers
- NewsOAuth2ConsumerService.countProvider()
- Return the total number of OAuth 2.0 providers registered with the consumer proxy. There are no parameters.
Example:
wsadmin>NewsOAuth2ConsumerService.countProvider() 20
Return a list of providers
- NewsOAuth2ConsumerService.browseProvider(int pageSize, int pageNumber)
- Return a list of Map objects that represent each OAuth 2.0 provider registered with the consumer proxy, in ascending ordered by provider name. The following information is returned for each map object in the returned list:
authHeader "true" or "false" authUrl the authentication url endpoint for the provider clientAuth the client authentication method in use name the name of the provider tokenUrl the token url endpoint for the provider urlParam "true" or "false"
- pageSize
- The maximum number of providers to list per page. Default is 20.
- pageNumber
- The number of the page to display. For example, if we specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. Default is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseProvider(50, 1)
Return a single provider
- NewsOAuth2ConsumerService.findProvider(string providerName)
- Return a Map with information about the registered OAuth 2.0 provider with the specified name.
- providerName
- The unique provider name.
Example:
wsadmin>NewsOAuth2ConsumerService.findProvider("provider123")
Register or update a provider
- NewsOAuth2ConsumerService.registerProvider(string providerName, string clientAuth, string authHeader, string urlParam, string authUrl, string tokenUrl)
- Registers or updates an existing OAuth 2.0 provider by name with the associated parameters.
- providerName
- The unique provider name.
- clientAuth
- The client authentication method for accessing this provider. Supported values out of the box are "standard" and "basic" per the specification.
- authHeader
- Value of "true" if credentials must be encoded in the authorization header, otherwise "false".
- urlParam
- Value of "true" if credentials must be specified as query parameters on the URI, otherwise "false".
- authUrl
- The authentication endpoint for the provider.
- tokenUrl
- The token endpoint for the provider.
Example:
wsadmin>NewsOAuth2ConsumerService.registerProvider("provider123", "standard", "true", "false", "???", "???")
Delete a provider
- NewsOAuth2ConsumerService.deleteProvider(string providerName)
- Deletes a provider by name if it exists, and has no existing associated clients or gadget bindings.
- providerName
- The unique provider name.
Example:
wsadmin>NewsOAuth2ConsumerService.deleteProvider("provider123")
Count clients
- NewsOAuth2ConsumerService.countClient(string providerName)
- Return the total number of OAuth 2.0 clients registered with the consumer proxy.
- providerName
- An optional filter to only count clients associated with the specified provider.
Example:
wsadmin>NewsOAuth2ConsumerService.countClient("provider123")
Return a single client
- NewsOAuth2ConsumerService.findClient(string clientName)
- Return a Map with information about the registered OAuth 2.0 client with the specified name.
- providerName
- The client name.
Example:
wsadmin>NewsOAuth2ConsumerService.findClient("client123")
Return a list of clients
- NewsOAuth2ConsumerService.browseClient(string providerName, int pageSize, int pageNumber)
- Return a list of Map objects that represent each OAuth 2.0 clients registered with the consumer proxy, in ascending ordered by provider name. The following information is returned for each map object in the returned list:
clientId Identifier issued by the authorization server when registering the client. clientSecret Secret issued by the authorization server when registering the client. ctype Client type, "confidential" or "public" are the supported values per the specification grantType "code" per the specification, or "client_credentials" per the specification name Name of the client. providerName Name of the associated provider that was previously registered redirectUri Client redirection uri
- providerName
- An optional filter to only browse clients associated with the specified provider.
- pageSize
- The maximum number of clients to list per page. Default is 20.
- pageNumber
- The number of the page to display. For example, if we specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. Default is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseClient("provider123", 50, 1)
Register or update a client
- NewsOAuth2ConsumerService.registerClient(string clientName, string providerName, string ctype, string grantType, string clientId, string clientSecret, string redirectUri)
- Registers or updates an existing OAuth 2.0 client by name with the associated parameters.
- clientName
- The name to associate with the client that must be unique in a deployment.
- providerName
- The name of the registered provider to associate with this client.
- ctype
- The client type. Supported values are "confidential" or "public".
- grantType
- The authorization grant type. Supported values are "code" or "client_credentials".
- clientID
- The identifier issued by the authorization server when registering your client.
- clientSecret
- The secret issued by the authorization server when registering your client.
- redirectUri
- The client redirection URI.
Example:
wsadmin>NewsOAuth2ConsumerService.registerClient("client123", "provider123", "confidential", "code", "my-client", "my-secret", "https://{opensocial}/gadgets/oauth2callback")
Delete a client
- NewsOAuth2ConsumerService.deleteClient(string clientName)
- Deletes a client by name if it exists, and has no existing associated gadget bindings that leverage this client.
- clientName
- The name of the client to remove.
Example:
wsadmin>NewsOAuth2ConsumerService.deleteClient("client123")
Bind a gadget
- NewsOAuth2ConsumerService.bindGadget(string widgetId, string serviceName, string clientName, string allowModuleOverride)
- Binds a gadget to a client with the specified service name and client name.
- widgetId
- The id of the widget.
- serviceName
- The name to associate with the gadget. The widgetId and service name must create a unique composite key for the deployment.
- clientName
- The name of the client to associate with this gadget.
- allowModuleOverride
- Value is "true" if the gadget overrides the provider default endpoint urls, else "false".
Example:
wsadmin>NewsOAuth2ConsumerService.bindGadget("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service", "client123", "false")
Delete a binding
- NewsOAuth2ConsumerService.unbindGadget(string widgetId, string serviceName)
- Deletes a gadget binding by widgetId and serviceName.
- widgetId
- The id of the widget.
- serviceName
- The name to associate with the gadget. The widgetId and service name must create a unique composite key for the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.unbindGadget("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service")
Return bindings
- NewsOAuth2ConsumerService.browseGadgetBinding(string widgetId, string clientName, int pageSize, int pageNumber)
- Return a list of Map objects that represent each OAuth 2.0 gadget bindings registered with the consumer proxy ordered by service name ascending. The following information is returned for each map entry in the returned list:
- clientName: the name of the associated client.
- allowModuleOverride: "true" or "false"
- serviceName: the name of the associated service
- uri: the gadget uri
- widgetId
- An optional filter to browse bindings only associated with a specific widget.
- clientName
- An optional filter to browse gadgets only associated with the specified client.
- pageSize
- The maximum number of bindings to list per page. Default is 20.
- pageNumber
- The number of the page to display. For example, if we specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. Default is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "client123", 50, 2)
Count bindings
- NewsOAuth2ConsumerService.countGadgetBinding(string widgetId, string clientName)
- Return the total number of OAuth 2.0 bindings registered with the consumer proxy.
- string widgetId, string clientName
- widgetId is an optional filter to count only bindings associated with a specific widget.
Example:
wsadmin>NewsOAuth2ConsumerService.countGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_servicex")
Return a single binding by gadgetUri
- NewsOAuth2ConsumerService.findGadgetBindingByUri(string gadgetUri, string serviceName)
- Return a Map with information about the registered OAuth 2.0 gadget bindings with the specified gadgetUri and service name.
- gadgetUri
- The uri for the gadget.
- serviceName
- The name associated with the gadget. A gadgetUri and service name create a unique composite key for a gadget in the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.findGadgetBindingByUri("http://www.acme.com/mygadget", "connections_service")
Return a single binding by widgetId
- NewsOAuth2ConsumerService.findGadgetBindingByWidgetId(string widgetId, string serviceName)
- Return a Map with information about the registered OAuth 2.0 gadget bindings with the specified widget id and service name.
- widgetId
- The id of the widget.
- serviceName
- The name associated with the gadget. A widgetId and service name create a unique composite key for a gadget in the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.findGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service")
Purging all tokens
- NewsOAuth2ConsumerService.purgeAllTokens()
- Purges all tokens persisted in the repository. This operation should be executed if the underlying encryption method has been modified.
Example:
wsadmin>NewsOAuth2ConsumerService.purgeAllTokens()
Parent topic:
Allow third-party applications access to data via the OAuth2 protocol
Related: