thinkgeo_cloud_quick_start_guide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
thinkgeo_cloud_quick_start_guide [2018/11/14 21:16] edgar [Exploring the ThinkGeo Cloud APIs] |
thinkgeo_cloud_quick_start_guide [2018/12/13 23:04] (current) brianr Bold notation was wrong |
||
|---|---|---|---|
| Line 26: | Line 26: | ||
| * **NativeConfidential** clients have full access to all the APIs you do, including those which manage clients and your user profile. They will authenticate by exchanging their ID and secret key for an identity token. Then, they will use that token to make requests to the ThinkGeo Cloud APIs. These clients are called "NativeConfidential" because their secret key must be kept confidential, and thus they are only suitable for use in native compiled applications or web services where the secret can be kept confidential, out of the hands of users. | * **NativeConfidential** clients have full access to all the APIs you do, including those which manage clients and your user profile. They will authenticate by exchanging their ID and secret key for an identity token. Then, they will use that token to make requests to the ThinkGeo Cloud APIs. These clients are called "NativeConfidential" because their secret key must be kept confidential, and thus they are only suitable for use in native compiled applications or web services where the secret can be kept confidential, out of the hands of users. | ||
| - | * **JavaScript** clients are intended to be used in web applications. They are simpler to use but can only access ThinkGeo Cloud plugins like elevation or the reverse geocoder. To use a JavaScript client, you only need to include the client ID in the URL of the API you are requesting -- no tokens are required. A JavaScript client's ID does not need to be kept confidential, but you should restrict the client so that it can only be used from web domains you control. | + | * **JavaScript** clients are intended to be used in web applications. They are simpler to use but can only access ThinkGeo Cloud plugins like elevation or the reverse geocoder. To use a JavaScript client, you only need to include the client ID in the URL of the API you are requesting -- no tokens are required. A JavaScript client's ID does not need to be kept confidential, but you should restrict the client so that it can only be used from web domains you control. See [[#Securing Your Clients|Securing Your Clients]] below for more information. |
| For now, let's use one of the default clients that come with your ThinkGeo Cloud account. For this exercise, we'll choose the Native Confidential client called "Sample Native Client". | For now, let's use one of the default clients that come with your ThinkGeo Cloud account. For this exercise, we'll choose the Native Confidential client called "Sample Native Client". | ||
| Line 36: | Line 36: | ||
| {{::thinkgeo_cloud_showkeys.png?350|}} | {{::thinkgeo_cloud_showkeys.png?350|}} | ||
| - | You can use the "Copy" button to copy these values to your clipboard. | + | You can use the "Copy" button to copy these values to your clipboard and use them in your application when authenticating. |
| - | ====Exploring the ThinkGeo Cloud APIs==== | + | **Note:** JavaScript clients will only have an API Key, since they are intended for use in browser-based applications where a secret cannot be kept secure. |
| - | The ThinkGeo Cloud offers a built-in way for you to explore the available APIs. To use it, click on the "API Reference" menu button. This will open a new browser tab to the ThinkGeo Cloud API Explorer. | + | ====Securing Your Clients==== |
| - | {{::thinkgeo_cloud_apiexplorer.png?800|}} | + | ===Keeping Secrets Safe=== |
| + | You should take all necessary precautions to keep safe the API Key and API Secret -- particularly the latter -- of your NativeConfidential clients. Since these two values together can always be used to request an access token, if unauthorized users gain access to both of them, they can use your client in their own applications and the API usage will count against your ThinkGeo Cloud account. | ||
| - | On this page, you can use the API Key and API Secret from your Sample Native Client to authenticate, and then experiment with the available APIs. | + | For maximum security, if you are developing a client application that will be distributed to end users, it's a good idea to create your own web service or serverless function such as AWS Lambda to store your client key and secret. This service or function can then field requests from your application, call out to the ThinkGeo Cloud to get an access token, and then return it to application. Your application can then use the access token to make ThinkGeo Cloud API calls. |
| - | To do so, click the "Authorize" button: | + | In contrast, JavaScript client API keys are less confidential, but you should take care to restrict them in the ThinkGeo Cloud web console so they can only be used from authorized sites or IP addresses. |
| - | {{::gisserverqsg_08_authorizebtn.png?nolink|}} | + | ===Restricting Who Can Use Your Client Keys=== |
| + | The ThinkGeo Cloud web console lets you configure your clients so they can only be used from approved locations. This is a **highly recommended step** to ensure that only you are able to use your client keys. | ||
| - | On this dialog, in the **Client Credentials (OAuth2, application)** section, do the following: | + | On the "Clients" page of the ThinkGeo Cloud web console, pick the client you wish to secure and click the blue **Pencil** button. The "Edit Client" dialog will appear. Near the bottom, you'll see a text box where you can add restrictions for your client. |
| - | - Paste your client's API Key into the "client_id" box. | + | JavaScript clients can whitelist usage by Origin Domain (e.g. mywebsite.com) or IP Address/IP Range (e.g. 203.0.113.78). NativeConfidential clients can use IP Address/IP Range restriction only. |
| - | - Paste your client's API Secret into the "client_secret" box. | + | |
| - | - Check the "ThinkGeoCloudAPIs" box. | + | |
| - | - Click the Authorize button. | + | |
| - | After successfully authenticating, you can close the dialog box. | + | ==Whitelisting Origin URIs== |
| + | {{::thinkgeo_cloud_edit_client_restrict_origins_sm.png?nolink|}} | ||
| - | You can now experiment with the following APIs be expanding the corresponding sections and clicking the "Try it out" button: | + | JavaScript clients can whitelist individual origin URIs (e.g. mywebsite.com) that are allowed to use the client. This is useful for web applications that are hosted on a particular domain, where no other web address should be allowed to use your client. You can enter: |
| - | * **Elevation** - A service that can find the elevation or grade of a point, line or area. | + | - A specific web domain, e.g. mywebsite.com |
| - | * **ReverseGeocoding** - Find the nearest points of interest, addresses, or intersections to a specified coordinate. | + | - Wildcards to represent all subdomains of a given domain, e.g. *.mywebsite.com |
| - | * **WorldImagery** - Tiled aerial imagery of the world. | + | |
| - | * **WorldStreets** - Tiled maps of the world in lightweight, high-performance vector format. | + | |
| - | {{::thinkgeo_cloud_elevation_explorer.png?nolink&800|}} | + | ==Whitelisting IP Addresses/IP Ranges== |
| + | {{::thinkgeo_cloud_edit_client_restrict_ips_sm.png?nolink|}} | ||
| - | Additionally, your Sample Native Client gives you access to a select few additional APIs that can be used to query or manage your account information, including: | + | JavaScript and NativeConfidential clients can whitelist individual IP addresses or IP address ranges that are allowed to use the client. You can enter: |
| - | * Accounts | + | - A specific IP address, e.g. 203.0.13.55 |
| - | * Get current account | + | - An IP range with wildcards, e.g. 203.0.113.* |
| - | * Update current account | + | - CIDR notation, e.g. 203.0.113.0/24 |
| - | * Clients | + | |
| - | * Create a new client | + | |
| - | * Delete client(s) | + | |
| - | * Get granted roles for a client | + | |
| - | * Get a specific client | + | |
| - | * Get a list of your clients | + | |
| - | * Update an existing client | + | |
| - | * Statistics | + | |
| - | * Get API usage statistics for your account (24 hour history) | + | |
| - | + | ||
| - | ====Interactive GIS Server Samples==== | + | |
| - | + | ||
| - | The GIS Server web console comes built-in with simple sample applications that help demonstrate the main services on offer: Elevation, Reverse Geocoding, World Imagery and World Streets. | + | |
| - | + | ||
| - | You can access these sample by clicking the "Plugin Test Pages" menu item to expand it, and then choosing a sample from the list below. | + | |
| - | + | ||
| - | Here's a screenshot of the Reverse Geocoder sample page, which lets you click on the map anywhere in the world to see a list of nearby points of interest. | + | |
| - | + | ||
| - | {{::gisserverqsg_10_revgeosample.png?nolink&800|}} | + | |
| - | + | ||
| - | ====Accessing the GIS Server From Your Application==== | + | |
| - | + | ||
| - | ThinkGeo offers two prepackaged API clients for developers who want to use the GIS Server APIs in their applications. Currently the following API clients are available: | + | |
| - | + | ||
| - | * .NET - [[https://www.nuget.org/packages/ThinkGeo.GisServer.Client|Available on NuGet]] | + | |
| - | * JavaScript - [[https://cdn.thinkgeo.com/gis-server/api/1.0.0/thinkgeo.gis-server.api.js|Minified Library]] | [[https://cdn.thinkgeo.com/gis-server/api/1.0.0/thinkgeo.gis-server.api.js.map|Source Map]] | + | |
| - | + | ||
| - | Would you like to see API clients in your language? Let us know what languages you'd like to see by emailing us at sales@thinkgeo.com. | + | |
| - | + | ||
| - | ====Sample Applications==== | + | |
| - | + | ||
| - | We're hard at work preparing a series of sample applications that use the official API clients to integrate with the GIS Server. These are designed to help you get a head start on your next project with ThinkGeo's GIS services. Check back soon! | + | |
thinkgeo_cloud_quick_start_guide.1542230175.txt.gz · Last modified: 2018/11/14 21:16 by edgar