Service Broker Authentication

It is important to understand how SmartObject security is handled. Consider the diagram below.

On the left-hand side of the diagram we have a collection of Providers, each with a different security requirement. On the right-hand side we have some users. Internal users have Active Directory credentials while External users have some other type of credential.

Users would interact with applications, and the Application security is the first authentication and authorization point. If the application needs to interact with K2 artifacts (for example, SmartObjects or Workflows), the user's credentials are passed from the application to the K2 server, where the user is authenticated against one of the Security Providers registered in K2. By default K2 is installed with an Active Directory security provider and authentication of AD users happens transparently. External users may be authenticated through a custom security provider or some other authentication mechanism. K2 uses the user's Security Label to determine which security provider to use when authenticating the user.

Now that the user is authenticated, let’s assume that they were attempting to execute a SmartObject method. All SmartObject calls need to pass through a Service Instance first, and the Service Instance Authentication Mode setting will determine what happens to the user's credentials.

When you are developing a custom service broker, you may need to determine the current authentication mode being used by the service instance so that you can connect to the target system appropriately. If you are using Impersonate or Service account with a system that accepts Windows credentials, you don’t need to perform any special processing. When using Static credentials or SSO, you will need to obtain the username and password for the service and use those to connect to the target system

K2 Service Instances can be configured with five possible Authentication Modes:

• Impersonate
• Service Account
• Static
• SSO (Single Sign-on)
• OAuth

The Authentication mode is set when configuring a Service Instance. The screenshot below shows where this setting is specified when using the SmartObject Tester utility:

Impersonate

When using the Impersonate setting, the currently-connected user's credentials are passed to the Provider. Although the K2 service account is executing the code in the Service Broker, K2 will "impersonate" the connected user and pass their credentials through to the provider transparently. As far as the Provider is concerned, it is as if the user connected directly to it. The Impersonate setting is mostly used when you need to preserve the security and authorization settings for your provider and ensure that users cannot execute methods or see data they are not allowed to see.

Service Account

The Service Account setting means that K2 will use the service account for the K2 server service to connect to the provider. This approach is mostly used when it is not necessary to pass the connected user's credentials through to the Provider, for example when querying lookup information or non-secure data. This is the simplest and easiest approach to use, but at the expense of security. Of course, you should ensure that the K2 service account has permission to perform the actions that may be called by the Service Broker.

Static

Static credentials allow you to configure a specific username, password and optional "Extra Data" that will be used to connect to the underlying provider. This approach is useful when the underlying Provider uses some other authentication mechanism and you can use a static username and password to connect to the provider.

In your Service Broker code you would retrieve the settings for the username and password and then connect to the Provider with these values. Note that this approach is used when it is not necessary to secure the data based on the connected user, because all calls to the provider will be performed in the context of the Static user account, not the context of the connected user.

When using Static credentials you can retrieve the configured username and password by accessing the following properties:

1
2
3
string username = base.Service.ServiceConfiguration.ServiceAuthentication.UserName;
string password = base.Service.ServiceConfiguration.ServiceAuthentication.Password;

SSO (Single Sign-on)

SSO (Single Sign On) uses an encrypted store of user "Keys". A user should set up their alternate credentials in the K2 Management site before this approach will be used. When SSO is used, K2 will check the encrypted "keys" store and obtain the connected user's security token for the target provider. K2 will then connect to the provider with this alternate token, without the user needing to provide their alternate credentials for the target system again.

Consider the diagram for this topic. Suppose that an Active Directory user is attempting to execute a method for a Salesforce-based SmartObject. Because Salesforce does not accept an Active Directory token, we've configured a SSO provider for Salesforce. Before connecting to Salesforce, K2 will check the SSO store for the current user's encrypted Salesforce username and password, and then connect to Salesforce with these alternate credentials. As far as the user is concerned, they don’t even know that K2 performs this credential-conversion in the background.

When using SSO, K2 will automatically retrieve the user's username and password from the SSO key store based on the Security Provider Label of the Service Instance configuration, The unencrypted username and password are then inserted into the
base.Service.ServiceConfiguration.ServiceAuthentication.UserName
and
base.Service.ServiceConfiguration.ServiceAuthentication.Password
properties at runtime. If the credentials aren’t found in the SSO "key" cache, a security exception will be thrown.

When using SSO you can retrieve the user's username and password for the target system by accessing the following properties:

1
2
3
string username = base.Service.ServiceConfiguration.ServiceAuthentication.UserName;
string password = base.Service.ServiceConfiguration.ServiceAuthentication.Password;

OAuth

The OAuth authentication mode is available for services that support OAuth 2.0 tokens. This authentication mode requires you to configure an OAuth resource ahead of time, and the specific configuration will depend on the service's OAuth specifications. You can learn more about setting up OAuth resources from the knowledge base article: KB001702 - How to configure OAuth in K2

When using OAuth you can retrieve the user's token for the target system by accessing the following property:

1
2
string oAuthtoken = base.Service.ServiceConfiguration.ServiceAuthentication.OAuthToken;

Because OAuth is built into the K2 platform you can use it for the outbound authorization for any custom broker you write. To do this you must pass the access token inside the bearer token and add it to the header of the request. The example below is how you retrieve and use the token.

1
2
3
4
5
//the URI of the service endpoint you are attempting to connect to, Box in this sample
string serviceEndpoint = "https://api.box.com/2.0/folders/FOLDER_ID";
string oAuthtoken = Service.ServiceConfiguration.ServiceAuthentication.OAuthToken;
string headerBearer = String.Format(System.Globalization.CultureInfo.InvariantCulture, "Bearer {0}", oAuthtoken);