Add basic authentication
|
In this example, you will create an Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control. that uses basic authentication Identifying the API requestor using a username and password passed in the HTTP header. to connect to GitHub, create a new repository and add a new issue as a task to be completed within the repository. |
Basic authentication requires Nintex Automation Cloud to provide a username and password in the header The section of the HTTP request that defines the operation of the request, including authorization. when making the request An attempt to use a feature or operation of a third-party API. of the API A programming interface that defines how software can be interacted with by other software.. The username and password must be accepted by the API for the API to process the request.
When using Xtensions with basic authentication, you must create a connection The stored authorization credentials for a connector. that stores the username and password so it can be passed to the API with the requests.
The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. and icon for this example are available here.
Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.
Looking for other examples?
The following examples also use basic authentication:
Or see the how-to guide on Basic authentication
Basic authentication
To add basic authentication to an OpenAPI Specification, you:
- Define the basic authentication object inside the securityDefinitions object.
- Reference to this basic authentication object inside the HTTP method objects that require authentication.
Tip: You can request additional connection information, such as a database name, using x-ntx-connection-properties, and validate your connection when it is created using x-ntx-connection-validation.
Create a GitHub account
If you do not already have a GitHub account, sign up to create your first GitHub account at https://github.com/join.
You will use this username and password to create a connection to your Xtension.
Define basic authentication
Step 1: Create the basic OpenAPI Specification
Create an OpenAPI Specification that:
- Uses the host The domain name of the third-party API's URL.api.github.com.
- Accepts HTTPS Hypertext Transfer Protocol Secure: the protocol by which websites and APIs communicate securely over the internet.and produces application/json.
- Uses a post method on /user/repos that
accepts two string and two boolean parameters in the
body The part of an HTTP request or response that can contain an arbitrary amount of data, such as the content of a form or web page. for the:
- Repository name.
- Repository description.
- Whether the repository can have issues.
- Whether the repository should be initialized with a README file.
- Uses a post method on
/repos/{owner}/{repo}/issues that accepts:
- Two strings in the path The part of the URL after the hostname that directs the request to a specific resources within the host. For example, the section after "example.com" in http://example.com/this/is/a/path. for the GitHub username and repository name.
- Two strings in the body for the issue title and description.
For more information on creating OpenAPI specifications with multiple operations, see Define the operations.
Extend this Xtension
You can extend the capabilities of this Xtension with file handling and controlling the configuration field interface. See:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "GitHub"
},
"host": "api.github.com",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"paths": {
"/user/repos": {
"post": {
"summary": "Create a repository",
"description": "Create a new repository",
"operationId": "createRepo",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"x-ntx-summary": "Repository name"
},
"description": {
"type": "string",
"x-ntx-summary": "Description of repository"
},
"has_issues": {
"type": "boolean",
"x-ntx-summary": "Can this repository have issues?"
},
"auto_init": {
"type": "boolean",
"x-ntx-summary": "Create an empty README?"
}
}
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/repos/{owner}/{repo}/issues": {
"post": {
"summary": "Create issue",
"description": "Creates an issue in the given repository",
"operationId": "createIssue",
"parameters": [
{
"name": "owner",
"type": "string",
"in": "path",
"required": true,
"x-ntx-summary": "Username"
},
{
"name": "repo",
"type": "string",
"in": "path",
"required": true,
"x-ntx-summary": "Repository name"
},
{
"name": "body",
"in": "body",
"schema": {
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"x-ntx-summary": "Title of issue"
},
"body": {
"type": "string",
"x-ntx-summary": "Description of issue"
}
}
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
Step 2: Create the security definitions object
Create the securityDefinitions object at the end of the OpenAPI Specification, before the final closing brace. Make sure you add a comma to the closing brace at the end of the paths object.
"securityDefinitions": {
}
Step 3: Create the basic authentication definition
Inside the securityDefinitions object, create an object to define the basic authentication. You can name the object any name that is unique within the OpenAPI Specification. In this example, we have named it basicAuth.
Add a type with a value of basic to the object to define it as basic authentication.
"securityDefinitions": {
"basicAuth": {
"type": "basic"
}
}
Step 4: Add a security array to the HTTP method objects
Inside each HTTP method object, create a security array.
"paths": {
"/repos/{owner}/{repo}/issues": {
"post": {
"summary": "Create issue",
"description": "Creates an issue in the given repository",
"operationId": "createIssue",
"security": [
{
}
]
}
}
}
Step 5: Add the security object reference to the array
Inside the security array in each HTTP method object, reference the security object you defined earlier by using its name as the key, and opening and closing brackets as the value.
"paths": {
"/repos/{owner}/{repo}/issues": {
"post": {
"summary": "Create issue",
"description": "Creates an issue in the given repository",
"operationId": "createIssue",
"security": [
{
"basicAuth": []
}
]
}
}
}
The OpenAPI Specification
This is the complete OpenAPI Specification that uses basic authentication to create a GitHub repository and issue.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "GitHub"
},
"host": "api.github.com",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"paths": {
"/user/repos": {
"post": {
"summary": "Create a repository",
"description": "Create a new repository",
"operationId": "createRepo",
"security": [
{
"basicAuth": []
}
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"x-ntx-summary": "Repository name"
},
"description": {
"type": "string",
"x-ntx-summary": "Description of repository"
},
"has_issues": {
"type": "boolean",
"x-ntx-summary": "Can this repository have issues?"
},
"auto_init": {
"type": "boolean",
"x-ntx-summary": "Create an empty README?"
}
}
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/repos/{owner}/{repo}/issues": {
"post": {
"summary": "Create issue",
"description": "Creates an issue in the given repository",
"operationId": "createIssue",
"security": [
{
"basicAuth": []
}
],
"parameters": [
{
"name": "owner",
"type": "string",
"in": "path",
"required": true,
"x-ntx-summary": "Username"
},
{
"name": "repo",
"type": "string",
"in": "path",
"required": true,
"x-ntx-summary": "Repository name"
},
{
"name": "body",
"in": "body",
"schema": {
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"x-ntx-summary": "Title of issue"
},
"body": {
"type": "string",
"x-ntx-summary": "Description of issue"
}
}
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"securityDefinitions": {
"basicAuth": {
"type": "basic"
}
}
}
Create the workflow
Step 1: Add your Xtension
Import the OpenAPI Specification you created into Nintex Automation Cloud:
- Open your Nintex Automation Cloud tenancy.
- Click Xtensions in the dashboard to open the Xtensions page.
- Click
in the Private connector list. - Click Choose a file. Navigate to the OpenAPI Specification on your computer.
- Wait for Nintex Automation Cloud to validate the file.
- Click Next.
- Nintex Automation Cloud detects the basic authentication security
template.
- Click Next.
- Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
- Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
- Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
- Click Publish.
Step 2: Create the workflow
Create a workflow that prompts the user for the name and description of their new repository, creates a repository and adds a boilerplate issue to complete a project plan for the repository.
For more information on creating workflows, see the Workflow Designer.
To create the workflow:
- Click Create workflow in your Nintex Automation Cloud tenancy.
- Configure the Start event to be a Public web
form with two text variables for the repository name and description.
For more information on designing forms in Nintex Automation Cloud, see Design a form.
- Drag a Create a repository action after the Start event.
- Configure the Create a repository action:
- Use the start variables for the repository name and description.
- Select Yes for Can this repository have
issues.
- Drag a Create issue action after the Create a repository action.
- Configure the Create issue action:
- Use your GitHub username in the Username field.
- Use the start variable for the Repository name.
- Configure the title and description of the new issue.
- Click Test to test the workflow.
- Save or publish the workflow.
Tip: If you want to troubleshoot an Xtension, select Development as the Assigned Use when you publish the workflow. Development workflows display more detailed error messages in their instance details. Republish your workflow as Production when you're ready to use it.