|
| 1 | +// Copyright (c) Microsoft Corporation. |
| 2 | +// All rights reserved. |
| 3 | +// |
| 4 | +// This code is licensed under the MIT License. |
| 5 | +// |
| 6 | +// Permission is hereby granted, free of charge, to any person obtaining a copy |
| 7 | +// of this software and associated documentation files(the "Software"), to deal |
| 8 | +// in the Software without restriction, including without limitation the rights |
| 9 | +// to use, copy, modify, merge, publish, distribute, sublicense, and / or sell |
| 10 | +// copies of the Software, and to permit persons to whom the Software is |
| 11 | +// furnished to do so, subject to the following conditions : |
| 12 | +// |
| 13 | +// The above copyright notice and this permission notice shall be included in |
| 14 | +// all copies or substantial portions of the Software. |
| 15 | +// |
| 16 | +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 17 | +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 18 | +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 19 | +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 20 | +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 21 | +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| 22 | +// THE SOFTWARE. |
| 23 | +package com.microsoft.identity.common.java.telemetry; |
| 24 | + |
| 25 | +import com.microsoft.identity.common.java.logging.Logger; |
| 26 | +import com.microsoft.identity.common.java.opentelemetry.AttributeName; |
| 27 | +import com.microsoft.identity.common.java.opentelemetry.SpanExtension; |
| 28 | +import com.microsoft.identity.common.java.util.StringUtil; |
| 29 | + |
| 30 | +import edu.umd.cs.findbugs.annotations.Nullable; |
| 31 | +import io.opentelemetry.api.trace.Span; |
| 32 | +import lombok.Getter; |
| 33 | +import lombok.Setter; |
| 34 | +import lombok.experimental.Accessors; |
| 35 | + |
| 36 | +/** |
| 37 | + * Model representing server telemetry data from the x-ms-clientdata response header |
| 38 | + * (/token responses) and the clientdata query parameter (/authorize redirect URLs). |
| 39 | + * Both use a pipe-delimited format: account_type|error|sub_error|caller_data_boundary|cloud_instance. |
| 40 | + * Contains server-side error codes, account type, cloud instance, and data boundary info. |
| 41 | + */ |
| 42 | +@Getter |
| 43 | +@Setter |
| 44 | +@Accessors(prefix = "m") |
| 45 | +public class ClientDataInfo { |
| 46 | + |
| 47 | + private static final String TAG = ClientDataInfo.class.getSimpleName(); |
| 48 | + |
| 49 | + /** Maximum length for any individual field when emitting to a span. */ |
| 50 | + private static final int MAX_FIELD_LENGTH = 256; |
| 51 | + |
| 52 | + /** |
| 53 | + * The name of the {@code clientdata} query parameter added to /authorize redirect URIs |
| 54 | + * by eSTS/MSA when {@code clidata=1} is included in the authorization request. |
| 55 | + * Use this constant everywhere the parameter name is referenced to avoid typos. |
| 56 | + */ |
| 57 | + public static final String CLIENTDATA_QUERY_PARAMETER = "clientdata"; |
| 58 | + |
| 59 | + /** Account type value for MSA accounts. */ |
| 60 | + private static final String ACCOUNT_TYPE_MSA_RAW = "m"; |
| 61 | + |
| 62 | + /** Account type value for AAD accounts. */ |
| 63 | + private static final String ACCOUNT_TYPE_AAD_RAW = "e"; |
| 64 | + |
| 65 | + /** Display value for MSA account type. */ |
| 66 | + private static final String ACCOUNT_TYPE_MSA = "MSA"; |
| 67 | + |
| 68 | + /** Display value for AAD account type. */ |
| 69 | + private static final String ACCOUNT_TYPE_AAD = "AAD"; |
| 70 | + |
| 71 | + /** |
| 72 | + * Positional index for account_type in the pipe-delimited format: |
| 73 | + * account_type|error|sub_error|caller_data_boundary|cloud_instance |
| 74 | + */ |
| 75 | + private static final int PIPE_INDEX_ACCOUNT_TYPE = 0; |
| 76 | + private static final int PIPE_INDEX_ERROR = 1; |
| 77 | + private static final int PIPE_INDEX_SUB_ERROR = 2; |
| 78 | + private static final int PIPE_INDEX_CALLER_DATA_BOUNDARY = 3; |
| 79 | + private static final int PIPE_INDEX_CLOUD_INSTANCE = 4; |
| 80 | + private static final int PIPE_MIN_SEGMENTS = 3; |
| 81 | + |
| 82 | + private String mError; |
| 83 | + private String mSubError; |
| 84 | + private String mAccountType; |
| 85 | + private String mCloudInstance; |
| 86 | + private String mCallerDataBoundary; |
| 87 | + |
| 88 | + /** |
| 89 | + * Parses an already-decoded pipe-delimited clientdata query parameter value. |
| 90 | + * The caller is responsible for URL-decoding before passing (e.g. values from |
| 91 | + * {@link com.microsoft.identity.common.java.util.UrlUtil#getParameters} are |
| 92 | + * already decoded). Decoding twice would corrupt values containing '+' or '%'. |
| 93 | + * Positional format: account_type|error|sub_error|caller_data_boundary|cloud_instance. |
| 94 | + * Requires at least 3 segments. |
| 95 | + * |
| 96 | + * @param decodedValue already-decoded pipe-delimited string, may be null. |
| 97 | + * @return parsed {@link ClientDataInfo}, or null on failure/empty input. |
| 98 | + */ |
| 99 | + @Nullable |
| 100 | + public static ClientDataInfo fromPipeDelimited(@Nullable final String decodedValue) { |
| 101 | + if (StringUtil.isNullOrEmpty(decodedValue)) { |
| 102 | + return null; |
| 103 | + } |
| 104 | + try { |
| 105 | + final String[] segments = decodedValue.split("\\|", -1); |
| 106 | + |
| 107 | + if (segments.length < PIPE_MIN_SEGMENTS) { |
| 108 | + Logger.warn(TAG, "clientdata pipe-delimited value has fewer than " + PIPE_MIN_SEGMENTS + " segments."); |
| 109 | + return null; |
| 110 | + } |
| 111 | + |
| 112 | + final ClientDataInfo info = new ClientDataInfo(); |
| 113 | + info.mAccountType = emptyToNull(segments[PIPE_INDEX_ACCOUNT_TYPE]); |
| 114 | + info.mError = emptyToNull(segments[PIPE_INDEX_ERROR]); |
| 115 | + info.mSubError = emptyToNull(segments[PIPE_INDEX_SUB_ERROR]); |
| 116 | + info.mCallerDataBoundary = segments.length > PIPE_INDEX_CALLER_DATA_BOUNDARY |
| 117 | + ? emptyToNull(segments[PIPE_INDEX_CALLER_DATA_BOUNDARY]) : null; |
| 118 | + info.mCloudInstance = segments.length > PIPE_INDEX_CLOUD_INSTANCE |
| 119 | + ? emptyToNull(segments[PIPE_INDEX_CLOUD_INSTANCE]) : null; |
| 120 | + return info; |
| 121 | + } catch (final Exception e) { |
| 122 | + Logger.warn(TAG, "Failed to parse clientdata pipe-delimited value: " + e.getMessage()); |
| 123 | + return null; |
| 124 | + } |
| 125 | + } |
| 126 | + |
| 127 | + /** |
| 128 | + * Sets each non-null field as a span attribute on the current span via {@link SpanExtension}. |
| 129 | + * account_type values are mapped: "m" -> "MSA", "e" -> "AAD". |
| 130 | + * Each field is truncated to {@value #MAX_FIELD_LENGTH} characters. |
| 131 | + */ |
| 132 | + public void emitToSpan() { |
| 133 | + final Span span = SpanExtension.current(); |
| 134 | + if (mError != null) { |
| 135 | + span.setAttribute(AttributeName.server_error.name(), truncate(mError)); |
| 136 | + } |
| 137 | + if (mSubError != null) { |
| 138 | + span.setAttribute(AttributeName.server_sub_error.name(), truncate(mSubError)); |
| 139 | + } |
| 140 | + if (mAccountType != null) { |
| 141 | + // account_type is an existing AttributeName; reuse it (m -> MSA, e -> AAD). |
| 142 | + final String mappedAccountType = mapAccountType(mAccountType); |
| 143 | + span.setAttribute(AttributeName.account_type.name(), truncate(mappedAccountType)); |
| 144 | + } |
| 145 | + if (mCloudInstance != null) { |
| 146 | + span.setAttribute(AttributeName.server_cloud_instance.name(), truncate(mCloudInstance)); |
| 147 | + } |
| 148 | + if (mCallerDataBoundary != null) { |
| 149 | + span.setAttribute(AttributeName.server_caller_data_boundary.name(), truncate(mCallerDataBoundary)); |
| 150 | + } |
| 151 | + } |
| 152 | + |
| 153 | + private static String mapAccountType(final String raw) { |
| 154 | + if (ACCOUNT_TYPE_MSA_RAW.equalsIgnoreCase(raw)) { |
| 155 | + return ACCOUNT_TYPE_MSA; |
| 156 | + } else if (ACCOUNT_TYPE_AAD_RAW.equalsIgnoreCase(raw)) { |
| 157 | + return ACCOUNT_TYPE_AAD; |
| 158 | + } |
| 159 | + Logger.warn(TAG, "Unknown account_type value in clientdata; emitting as UNKNOWN."); |
| 160 | + return "UNKNOWN"; |
| 161 | + } |
| 162 | + |
| 163 | + @Nullable |
| 164 | + private static String truncate(@Nullable final String value) { |
| 165 | + if (value == null || value.length() <= MAX_FIELD_LENGTH) { |
| 166 | + return value; |
| 167 | + } |
| 168 | + return value.substring(0, MAX_FIELD_LENGTH); |
| 169 | + } |
| 170 | + |
| 171 | + @Nullable |
| 172 | + private static String emptyToNull(final String value) { |
| 173 | + return StringUtil.isNullOrEmpty(value) ? null : value; |
| 174 | + } |
| 175 | +} |
0 commit comments