lilnobp さんのグループアクティビティ

Token Authentication using the REST API

Christopher Gillis — Thu, 02 May 2019 12:30:00 GMT

Aras Innovator introduced an Authentication Server feature in 11.0 SP12 and has been fleshing it out with each new service pack. In 11.0 SP15, it is possible to request an OAuth token from this server that can be used with the RESTful API as an alternative to basic authentication. Using tokens is preferred for external apps as they don't require you to keep your users' passwords in memory while your app runs. Because tokens expire after a set time, you can also rest assured that if a malicious party later acquires the token, they won't have access to your system.

In this blog post, we'll be going over examples of both requesting an OAuth token from the Aras Innovator server as well as using that token to authenticate additional requests. You can also check out this Authentication Example on GitHub for a simple app that will request a token and use that token to query the Parts in a database.

Register Your App

One of the features of the Authentication Server is to limit what apps can request a token. The Authentication Server keeps a list of registered apps that are able to request tokens, so external applications cannot get tokens by default. If you don't wish to do any additional configuration, you can use the default "IOMApp" client registry. However, we recommend adding a new client registry to register your app with the server by following the steps below.

Open the \OAuthServer\OAuth.config in your preferred text editor
Scroll down to the bottom until you see <clientRegistry id="IOMApp">
Copy this node and all of its child nodes
Paste them as a new section just below the original node
Give a new ID to this registry corresponding to the purpose of your app
Make sure this new registry has enabled="true"

Make note of the ID you give this new registry. You will need to use it in the body of your request for a token which is covered later in this blog.

Get the OAuthServer URL

The first thing we'll want to do is query for the location of the OAuthServer. Because Aras Innovator allows most of its components to exist on separate servers, the OAuthServer may not be available from the same server as our Instance URL. However, the Innovator Server does have a way to query for this information by appending /Server/OAuthServerDiscovery.aspx to the end of your Instance URL: http://localhost/InnovatorServer/Server/OAuthServerDiscovery.aspx .

If you're using something like Postman to follow along with this blog, you can simply perform a get request on this URL with an empty body. The result of this request should look something like below.

{
"locations": [
{
"uri": "http://localhost/InnovatorServer/oauthserver/"
}
]
}

The URL we will use is stored in the uri property of the JSON returned from our request. The JSON path you can use to retrieve this information is locations[0].uri.

Get the Token Endpoint

Now that we have the URL of the OAuthServer, we will need to retrieve the exact URL that we can use to query for the token. This next URL is based on the OpenID discovery specification. We will take the OAuthServer URL from our previous step and append .well-known/openid-configuration to the end of it: http://localhost/InnovatorServer/oauthserver/.well-known/openid-configuration. Again, we can query on this URL with a simple GET request without passing anything through the body.

The response to this request is significantly longer, but it should contain our token endpoint somewhere near the top.

{
"issuer": "OAuthServer",
"jwks_uri": "http://localhost/InnovatorServer/oauthserver/.well-known/openid-configuration/jwks",
"authorization_endpoint": "http://localhost/InnovatorServer/oauthserver/connect/authorize",
"token_endpoint": "http://localhost/InnovatorServer/oauthserver/connect/token",
"userinfo_endpoint": "http://localhost/InnovatorServer/oauthserver/connect/userinfo",
"end_session_endpoint": "http://localhost/InnovatorServer/oauthserver/connect/endsession",
...

The JSON path to retrieve this data is simply token_endpoint.

Get Token

The final request we'll use to retrieve our token will use the token endpoint URL retrieved in the previous step. Because this token will be linked to a user's credentials, we will need to pass in additional information before making our request. If you're following along with Postman, you can use the Multipart Form to specify the following pieces of information in your body.

grant_type : "password"
- Currently, I believe "password" is the only authentication type allows. Aras as a whole is moving towards more types of authentication in 12.0, so this is likely to change in the upcoming releases.
scope : "Innovator"
- The scope of information this token will be able to access. "Innovator" will be used for almost all purposes.
client_id : "IOMApp"
- The ID of your client app you configured in the first step of this blog.
username : "YOUR_USER_NAME"
- Any requests made using the returned token will share the same permissions as this user
password : "YOUR_MD5_HASHED_PASSWORD"
database : "YOUR_DATABASE_NAME"
- This should be the name of the database that this token will be able to access. "InnovatorSolutions" is the default name of Aras databases.

After configuring your body, you can send a POST request to the token endpoint URL with the body containing the properties defined above. The response will contain both the OAuth token as well as how long you will have until that token expires.

{
"access_token": "YOUR_TOKEN",
"expires_in": 3600,
"token_type": "Bearer"
}

The JSON path to this token will be access_token. By default, the IOMApp token expires in 3600 seconds or 1 hour.

Make Request with Token

If you've ever used our previous RESTful blog, you'll know that we authenticated previously by passing in the username and hashed password into the AUTHUSER and AUTHPASSWORD headers respectively. With the token, we will authenticate using the standard HTTP Authorization header. Token authentication using this header follows the format below.

Authorization : Bearer {YOUR_TOKEN}

Note that the word "Bearer" must come before your token in the header. If you're using Postman, there should be a way to configure authentication differently than other headers which should automatically add in this word for you. Alternatively, depending on the programming language you're using to perform this request, there may be a special authentication class or library which will automatically add "Bearer" into the header for you as well.

Regardless, once you have your Authorization header configured, you can follow along with our previous RESTful blog, and you should notice that you can query for all of the same information. You can also confirm that the permission model is still in place by querying for items to which you do not have access.

LOOKING FOR MORE ARAS INSPIRATION?

Subscribe to our blog and follow @ArasLabs on Twitter for more helpful content! You can also find our latest open-source projects and sample code on the Aras Labs GitHub page.

Aras REST API - How do you navigate / create a BOM Structure using the REST API?

manasbuilds — Wed, 16 Sep 2020 14:52:02 GMT

Hello Aras Community Members

Does the ARAS REST API allow you to navigate the BOM structure, starting with a Part? For example, if I have a BOM structure as shown below, I would like to start with any Part in the structure and navigate down the BOM tree. Can anyone share the REST API endpoint for making this work, or point to a specific section in the API guide?

Part A

- Part A1

- Part A2

--- Part A21

--- Part A22

------Part A221

Second question: Does the REST API allow users to create a BOM structure, e.g. a BOM tree as above?

Third question: Does the REST API allow users to update the BOM structure?

Uploading Files via the Aras Innovator REST API

Eli Donahue — Tue, 25 Jun 2019 19:30:00 GMT

If you've been following our previous posts on the Aras Innovator RESTful API, you know just about everything you need to implement your own custom integrations, clients, tools, and mobile applications. You can perform basic CRUD operations to create and modify Innovator data, and you can use OAuth tokens to authenticate requests. All that's missing is file handling!

Files behave a little differently than other items in Innovator, so the Aras Innovator RESTful API includes some special actions for uploading files to the vault. In this post, we'll cover these vault-specific endpoints to show how you can add file uploading to your custom projects.

As in our previous posts about the RESTful API, we're using an API development tool to demonstrate the HTTP requests needed to upload files. That way each, the example is language-agnostic and you can follow along without jumping right into code. If you want to follow along with the blog, you can download Postman for free.

If you want to see how you can use these HTTP requests in code, check out the rest-upload-example project on the Aras Labs GitHub. The project provides a simple HTML form that allows the user to enter the credentials for an Aras Innovator instance and select a file to upload. The included submitForm() JavaScript function authenticates the user and uploads the file to the specified vault via the HTTP requests covered below.

Screenshot of the rest-upload-example community project on the Aras Labs GitHub

Authentication

We'll use OAuth to authenticate the HTTP requests in this example, so the first thing we need to do is get a new token from Innovator's OAuth server. We've covered using OAuth tokens with Aras Innovator in a previous blog post, so I won't dive into the details here. Basically, you'll need a POST request with the following information passed in the body:

grant_type : "password"
scope : "Innovator"
client_id : "IOMApp"
- "IOMApp" is the default client id for new Aras Innovator instances. You can find out how to change it or add a new client id here.
username : <Innovator User>
- Any requests made using the returned token will share the same permissions as this user
password : <MD5 password hash>
- The rest-upload-example project demonstrates one way to create the hash from the password string entered by the user. Check out getConnectionInput() in my-upload.js.
database : <database name>

If you're using Postman to test or follow along, your request and reply should look something like this:

Request a new OAuth token from the Aras Innovator OAuth server.

Once you get the request back from the vault server, you can get the token from the JSON object that's returned. To authenticate our subsequent requests, we just need to include this token in the "Authorization" header.

Note: You could use basic authentication to send these requests, but OAuth tokens are the preferred authentication approach moving forward.

Uploading the File

Now that we have our token for authenticating requests, there are just three basic steps to upload a file to Innovator via the RESTful API: get a transaction id, upload the file contents, and commit the transaction.

1. Begin the Upload Transaction

The first step to upload a file to Innovator is to get a transaction id from the vault server. All we need to do to is send a POST request, authenticated with our token, to the vault.BeginTransaction endpoint. The result will be a JSON object with a "transactionId" property.

Get a new transaction id from the vault server with the vault.BeginTransaction endpoint.

We'll include the transaction id in all of the calls to upload the file. This string should be unique to each file that you upload. If you need to upload multiple files, you'll need to request a new transaction id for each. This helps the vault server process each file upload transaction.

Note: Postman does have an "Authorization" tab where you can choose the type of authentication you want to use and enter the token or credentials. That works, but I've opted to explicitly define the Authorization header to show how to use the OAuth token without a specific client feature.

2. Upload the File

Now that we have started a transaction with the vault server, we can start uploading the file. In this example, we're uploading a small, simple text file to Innovator with a single HTTP request. However, you can also upload a file in "chunks" if you have a large file or network constraints. The uploadFile() function in the rest-upload-example community project demonstrates how you can programmatically split your file upload into multiple requests.

In the screenshot below, you can see we're passing 5 headers:

Content-Disposition: attachment; filename*=utf-8''<filename>
- If your filename includes spaces or special characters, you'll need to encode them. Check out this reference for character codes.
- Be sure to include the two single quotes before the file name (not a single double quote).
Content-Range: bytes <start index>-<end index>/<length>
Content-Type: "application/octet-stream"
transactionid: <transaction id from previous step>
Authorization: Bearer <OAuth token>

If you're uploading a file in a single HTTP request, setting the Content-Range header is pretty simple. The start index will be 0, end index will be length-1, and length will be the file size in bytes. For a 53 byte file, the Content-Range header will be set to "bytes 0-52/53".

If you're uploading a file with multiple HTTP requests, you'll need to calculate the Content-Range for each request. If I were uploading the 53 byte file in 10 byte chunks, I would use the chunk's original start and end index, as well as the file size. For example, the third 10 byte chunk of a 53 byte file would have the Content-Range header "bytes 20-29/53".

The body of each request should contain the bytes referenced by the Content-Range header. In this case, I'm uploading a whole text file so I can just paste the contents into the body of the Postman request.

Upload one or more file chunks using the vault.UploadFile endpoint.

You'll notice that the vault.FileUpload request above returned an empty body. This is expected. To check whether the upload succeeded or failed, check the status code that is returned. A 200 status code indicates success. If you're getting a 40* or 500 error, double check your server credentials and request headers.

3. Commit the Upload Transaction

Once the contents of the file have been uploaded, we can commit the transaction. Committing the transaction tells the server we're done uploading file content and the file can be moved from the transaction folder to its final destination in the vault. The file doesn't exist in the vault until we get a successful response from the commit transaction request.

The headers of the vault.CommitTransaciton request are pretty straightforward. We'll use the same transactionid and Authorization headers that we used to upload the file contents, however the Content-Type header will look a little different.

Content-Type: multipart/mixed; boundary=<boundary string>
transactionid: <transaction id>
Authorization: Bearer <OAuth token>

We need to define a boundary string to help the vault server parse the contents of the request body. You can use a randomly generated GUID, the item id, etc. Just make sure that the boundary you define in the header and the string you use in the request body match.

Headers for the vault.CommitTransaction endpoint

The body of the vault.CommitTransaction request is composed of specially formatted text. Here's the general format:

--<boundary string>
Content-Type: application/http

POST http://<server>/<web alias>/Server/odata/File HTTP/1.1
Content-Type: application/json

{"id":"<file item id>","filename":"<filename>","file_size":<total size in bytes>,"Located":[{"file_version":1,"related_id":"<vault id>"}]}
--<boundary string>--

A couple things to note about the body format:

The strings highlighted in yellow will specific to your Innovator instance and the file you're uploading.
The <boundary string> parameter should be replaced with the boundary string defined in the request's Content-Type header.
The spacing in the body text is very important. All line endings should be carriage returns (\r\n). Depending on how you're building the request body, you may or may not need to explicitly enter these line ending characters.

A sample request body and result for vault.CommitTransaction

A successful request will return a 200 status code and some body text about the new File item. You can parse the body text to get the JSON object and access the item's properties.

Confirming the Upload

The commit request will return some metadata about the new File item, but you can perform a GET request if you want to get specific metadata. The screenshot below shows how to request a File item from Innovator, just like any other ItemType. You can also retrieve the contents of a file by adding "/$value" to the end of the request url.

GET request to retrieve a File item from the Innovator server

Now you can include file uploading in your custom projects that use the Aras Innovator RESTful API! What are you going to try first? Share your ideas and questions in the comments below.

Looking for more Aras inspiration?

Subscribe to our blog and follow @ArasLabs on Twitter for more helpful content! You can also find our latest open-source projects and sample code on the Aras Labs GitHub page.

My web Asp.net login failed

DucTran — Mon, 06 Jul 2020 08:21:34 GMT

Hi everyone,

I have to make a web with ASP.NET and published to host http://inn.ddns.com/myweb. The web accessed normally.

The login form has:

Server address: http://inn.ddns.com/myaras
database: INN-TEST
username: admin
password: innovator

--> When a press login button, nothing happen (no alert failed or succeed, no error string)

If I replaced server address by local name (http://inn-srv/myaras), It working fine.

I try to config IIS server, open port, .. but not succeed. Pls help me.

lilnobp さんの グループ アクティビティ