|
1 | 1 | # SecurityTokenHelper |
2 | | -WCF behavior extension allows to retrieve a token from a token service endpoint and to add the token to the main call for a given binding like WebHttpBinding |
| 2 | +[](https://dev.azure.com/mytestings/Integrations/_build/latest?definitionId=30) |
| 3 | + |
| 4 | +SecurityTokenHelper is a WCF endpoint behavior extension that helps authenticating calls in BizTalk, it also contains TokenHelper class that use to get token with without using WCF. |
| 5 | + |
| 6 | +## TokenHelper Functions |
| 7 | + |
| 8 | + - string GetBasicAuthEncoded(string username, string password): encodes username:password string in Base64 format to be used in basic auth header. |
| 9 | + - GetToken |
| 10 | + ``` |
| 11 | + string GetToken(HttpMethodEnum method, string url, HeaderCollection headers, string contentType, string body, string tokenPath) |
| 12 | + string GetToken(HttpMethodEnum method, string url, HeaderCollection headers, string contentType, string body, string tokenPath, Guid tokenId, int tokenExpiresIn, bool cachedToken) |
| 13 | + ``` |
| 14 | +### Parameters |
| 15 | +| Parameter| Type| Description | |
| 16 | +|--|--|--| |
| 17 | +| method | HttpMethodEnum (Required) | The http method used when calling the token service endpoint.<br/>[POST (Default),GET] |
| 18 | +| url | string (Required) | The token service endpoint url. |
| 19 | +| headers | HeaderCollection (Optional) | Headers to be used to make successful call. |
| 20 | +| contentType | string (Optional) | The content-type for the body is being sent in the call, Required if the body parameter is not empty | |
| 21 | +| body | string (Optional) | The body of the call. |
| 22 | +| tokenPath | string (Required)| The XPath or JPath for the token value e.g. for JSON: $..access_token, For Xml: /Token/Access_Token.| |
| 23 | +|cachedToken| bool (Optional)| determines if the token to be cached, or retrieved from Token Cache| |
| 24 | +| tokenId | guid (Optional) | Token identifier, must be determined if cachedToken is set to true.| |
| 25 | +| expriesIn | int (Optional) | the period in seconds for the token before it expires, required if cachedToken is set to true, and must have a value greater than 0| |
| 26 | + |
| 27 | +## SecurityTokenHelperBehavior |
| 28 | +The WCF Behavior extension to be used with WCF bindings to retrieve the token from a token service endpoint before performing the main call. |
| 29 | + |
| 30 | +### Properties |
| 31 | + |
| 32 | +|Property | Type| Description | |
| 33 | +|--|--|--| |
| 34 | +| HttpMethod | HttpMethodEnum (Required) | The http method used when calling the token service endpoint.<br/>[POST (Default),GET] |
| 35 | +| AuthEndpoint | string (Required) | The token service endpoint url. |
| 36 | +| Headers| HeaderCollection (Optional) | Headers to be used to make successful call. |
| 37 | +| ContentType| string (Optional) | The content-type for the body is being sent in the call, Required if Body property is not empty | |
| 38 | +| Body | string (Optional) | The body of the call. |
| 39 | +| TokenPath | string (Required)| The XPath or JPath for the token value e.g. for JSON: $..access_token, For Xml: /Token/Access_Token.| |
| 40 | +|CacheToken| bool (Optional)| determines if the token to be cached, or retrieved from Token Cache| |
| 41 | +| TokenId| guid (Optional) | Token identifier, must be determined if CacheToken is set to true.| |
| 42 | +| TokenExpiresIn| int (Optional) | the period in seconds for the token before it expires, required if CacheToken is set to true, and must have a value greater than 0| |
| 43 | +|TokenUsage| TokenUsageEnum(Required) | Specifies where to use the retrieved token in the main call, [Header (Default),QueryParameter]| |
| 44 | +|TokenKey| string (Required)| the name of the header or the query string parameter that holds the retrieved token e.g. Authorization| |
| 45 | +|TokenPrefix| string(Optional)| a prefix to be added before the token e.g. Bearer | |
| 46 | +|TokenSuffix| string (Optional) | a suffix to be added to the token | |
| 47 | + |
| 48 | + |
| 49 | +## SecurityTokenHelperElement |
| 50 | +This is the WCF behavior extension element, that will load all the configuration from the config file, and it presents the behavior extension in BizTalk. |
| 51 | + |
| 52 | +### Properties |
| 53 | + |
| 54 | +|Property | Type| Description | |
| 55 | +|--|--|--| |
| 56 | +| HttpMethod | HttpMethodEnum (Required) | The http method used when calling the token service endpoint.<br/>[POST (Default),GET] |
| 57 | +| AuthEndpoint | string (Required) | The token service endpoint url. |
| 58 | +| Headers| string(Optional) | Headers to be used to make successful call, this is multiline property and each header is represented in a single line. |
| 59 | +| ContentType| string (Optional) | The content-type for the body is being sent in the call, Required if Body property is not empty | |
| 60 | +| Body | string (Optional) | The body of the call. |
| 61 | +| TokenPath | string (Required)| The XPath or JPath for the token value e.g. for JSON: $..access_token, For Xml: /Token/Access_Token.| |
| 62 | +|CacheToken| bool (Optional)| determines if the token to be cached, or retrieved from Token Cache| |
| 63 | +| TokenId| guid (Optional) | Token identifier, must be determined if CacheToken is set to true.| |
| 64 | +| TokenExpiresIn| int (Optional) | the period in seconds for the token before it expires, required if CacheToken is set to true, and must have a value greater than 0| |
| 65 | +|TokenUsage| TokenUsageEnum(Required) | Specifies where to use the retrieved token in the main call, [Header (Default),QueryParameter]| |
| 66 | +|TokenKey| string (Required)| the name of the header or the query string parameter that holds the retrieved token e.g. Authorization| |
| 67 | +|TokenPrefix| string(Optional)| a prefix to be added before the token e.g. Bearer | |
| 68 | +|TokenSuffix| string (Optional) | a suffix to be added to the token | |
| 69 | +## Remarks |
| 70 | + |
| 71 | + |
| 72 | +## Installation |
| 73 | +Download and install the latest release. |
| 74 | +This extension is designed to be used with BizTalk, but it can also be used with other applications. |
| 75 | +There are two ways to add this extension to the configuration, it can be added to the global machine.config file, or it can be added to the host instance only. |
| 76 | + |
| 77 | +### Adding the extension to machine.config |
| 78 | +the extension must be added to both .Net framework versions (32 bit and 64 bit). |
| 79 | + |
| 80 | + |
| 81 | +`%windir%\Microsoft.Net\Framework\<.NET Version>\config\machine.config` |
| 82 | + |
| 83 | +`%windir%\Microsoft.Net\Framework64\<.NET Version>\config\machine.config` |
| 84 | + |
| 85 | + |
| 86 | +locate behaviorExtensions section and add the following line |
| 87 | +``` |
| 88 | +<add name="SecurityTokenHelper" type="BizTalkComponents.WCFExtensions.SecurityTokenHelper.SecurityTokenHelperElement, BizTalkComponents.WCFExtensions.SecurityTokenHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f8600b34c8012b7b" /> |
| 89 | +``` |
| 90 | + |
| 91 | +### Adding the extension to BizTalk Host Instance |
| 92 | +In BizTalk Administrator Console, go to Platform Settings --> Adapters and select the WCF adapter you would like to add the extension to, then select the send handler you want to make the extension available with, right click on it and then select properties, Click Properties button in Adapter Handler Properties, then select WCF extensions, copy the code below to a new Xml file then click on Import. |
| 93 | +``` |
| 94 | +<configuration> |
| 95 | + <system.serviceModel> |
| 96 | + <extensions> |
| 97 | + <behaviorExtensions> |
| 98 | + <add name="SecurityTokenHelper" type="BizTalkComponents.WCFExtensions.SecurityTokenHelper.SecurityTokenHelperElement, BizTalkComponents.WCFExtensions.SecurityTokenHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f8600b34c8012b7b" /> |
| 99 | + </behaviorExtensions> |
| 100 | + </extensions> |
| 101 | + </system.serviceModel> |
| 102 | +</configuration> |
| 103 | +``` |
| 104 | + |
0 commit comments